Contribution guidelines

Troubleshooting and issues

Should you discover a bug, please open a ticket using the GitHub issue function. If you don't know the resolution, follow standard GitHub reporting guidelines, stating your system, what you did and tried. See the scheme below for some pointers. Here are two templates:

And here's yet another template:

#### Current behavior
- Are you using the latest available version? If not, first update and verify the problem still exists.
- What is the problem?
- Include a screenshot if it makes sense.

#### Expected behavior
- What should be happening?
- Include a screenshot if it makes sense.

#### How to reproduce
- Please explain the steps to reproduce the problem. If you are having an issue with your machine or build tools, the issue belongs on another repository as that is outside of the scope of this project.

#### Environment
- Let us know in what environment you're running into the issue.
- E.g. specify the OS: (Windows version/Linux distro/OSX version) 
- Specify Tools and versions

If you run into issues during the installation and for general software support, best make a thread on the community portal Orion or ask a quick question on the Constellation discord server.

Pull requests (PRs)

Code review

Try to review PRs where your review is requested within a few days. This should be nearly-top-priority work.
If you don’t understand something then ask for an explanation. For the author: this explanation should ideally be added as a comment - you’re going to write it anyway, and future readers are likely to be just as confused as the reviewer.

Commiting a PR

Please make pull requests (PRs) to the dev branch, which is routinely merged into master. Here's a template:

Pull requests

And now for some pointers:

PRs exist to be reviewed - design them with a reader in mind!
Write a helpful PR description that explains what’s in the PR and why, possibly will bullet points of different changes. Draws attention to anything of particular note, references related tickets etc.
Include the ticket name in the PR title where possible.
Submit PRs in a “finished” state. If you want to use a PR to let people review a WIP branch, make sure to label it obviously.
Keep PRs to a single topic. Instead of proposing the merge of a branch with very different sorts of changes to the code base, rather make separate PR's. If you find yourself making unrelated changes, pull those commits out into another PR and submit them separately (i.e. do not include them in the original PR). If you can’t remove unrelated changes from your PR (because you depend on them), then add a note that your PR depends on the other one and should not be merged before it. You can still put it up for review. Take especial care to manage changes that are likely to have many conflicts (like formatting or refactoring changes) in their own PRs.
Consider rebasing your PRs before submitting to structure them into a few logical commits that can be reviewed separately.
Ideally, every commit should pass tests and CI (continuous integration)
Use your judgment when requesting review
Almost all PRs should have a review, and ideally the reviewer should merge them. If they’re happy but haven’t merged, or you need to fix conflicts, then it’s fine to merge the PR yourself.
Documentation-only PRs can be merged without a review
In some cases very small PRs like trivial bug fixes can also be merged without a review
PRs with changes to code that another team member is currently working on should always request a review from the affected team member.
Comment if you want attention from someone (e.g. a re-review after changes). Github does not make it easy to signal this state otherwise, and people may not be notified if you just push commits.

Here's a general text on recommendations:

Code style

For functions, method and traits, we suggest IntelliJ standard docstring everywhere and or generally follow the Scala standards. See

Here's a bloated example:

/** Improves a guess for a square root computation.
  * 
  * Provided a value interpreted as the square of a value x and a guess 
  * for x, improve the guess using the Babylonian method. To that end, 
  * compute the multiplicative complement of the guess and return the 
  * mean. Iterating this function on xg will give a value converging towards 
  * the real square root.
  * @param x2 : Value we seek the square root x of.
  * @param xg : Initial guess for x.
  * @return : An improvement over xg.
  * @note : The value xg should be positive and smaller than x2.
  * @example : improvedSqrtGuess(4, 2.3) // evaluates to 2.0196...
  * @see : [[https://en.wikipedia.org/wiki/Newton%27s_method Newtons_method]]
  * @todo : Remove all unnecessary comments from the body of the function
  */
def improvedSqrtGuess(x2 : Double, xg : Double): Double = { 
  val xc = x2 / xg // The multiplicative complement of the guess.
  (xg + xc) / 2
}

resp. a minimal one:

/** Retruns the improved guess for a square root computation. */
def improvedSqrtGuess(x2 : Double, xg : Double): Double = { 
  val xc = x2 / xg // The multiplicative complement of the guess.
  (xg + xc) / 2
}

One may generate a html page via sbt doc or just doc in the intelliJ sbt console. This file is then generated under constellation/target/scala-x.xx/api/index.html.

Provide feedback

Saved searches