How to contribute - eclipse-capella/capella GitHub Wiki

Issues tracker

Capella uses Github to track ongoing development and issues.

Be sure to search for existing bugs before you create new ones.

Legal stuff

Apologies in advance for the extra work required here. This is necessary to comply with the Eclipse Foundation's IP policy.

In order for any contributions to be accepted you MUST do the following things.

  • Sign the Eclipse Contributor Agreement. To sign the Eclipse ECA you need to:
    • Create an Eclipse Account with the same mail than your GitHub account, if you don't already have one. Anyone who currently uses Eclipse Bugzilla or Gerrit systems already has one of those. If you don’t, you need to register.
    • Login to sign ECA, select the “Contributor License Agreement” tab.
  • Add your github username in your Eclipse Foundation account settings. Log in it to Eclipse and go to account settings.

For more details, you can read the eclipse contribution guide.

In Github Settings:

  • Email : Uncheck Keep my email addresses private as Github will replace sometimes your Author email with an "users.noreply.github.com" one, which are not compliant.

Development Environment (IDE)

https://github.com/eclipse/capella/wiki/Development-Environment

How to configure the repository

First of all you must fork and clone the capella repository. Once the clone is over, you should have something similar to this:

That's it, you can contribute. You can directly go to the next section...

But in order to keep your repository synchronized with the original eclipse repository you can add a new remote, in this example we call it eclipse, but the name is up to you. If you do decide to use another name, please update the fetch data accordingly:

Pointing to https://github.com/eclipse/capella.git

Once this is done, we must configure the fetch for this remote, you can only add the main branches like so:

  • refs/heads/master:refs/remotes/eclipse/master
  • refs/heads/v*:refs/remotes/eclipse/v*

Once this is done, you should have something like this:

In order to synchronize your fork just rebase your fork branches on the latest main branches.

How to contribute code

Code

See Development Guidelines

You have to import capella.epf preferences to use proper text formatting. (File > Import > General > Preferences and choose the capella.epf at the root of Capella Git repository with all options checked)

License headers

Make sure that newly added source files have a proper license header. (on all .java, .xml, .properties files ) You can refer to any existing file to see Copyright header format.

Documentation

Please make sure that documentation is updated accordingly to new added features and changed interfaces.

Automated tests

Before submitting a patch, make sure that new added features and fixed issues are covered by automated tests. Tests are defined in tests/ git repository.

Pull requests

On your .gitconfig, add commit.cleanup: verbatim, core.autocrlf: input, core.longpaths: true

Commit title and Pull Request title format

The following format must be used: #issueid Small description of your bug

Here are some valid description examples:

  • #12 Add JUnits for diagram creation
  • #15 Remove delete button precondition
  • #16 Fix create component tool
  • #13 Update target platform

Request a review

Use 'draft' button if the pull request is not yet ready. When your code is finished, you can add label review-requested on your Pull Request when you are sure you want a review

Multiple commits policy

A pull request (PR) can contain multiple commits as long as they are all related to the same bugfix or feature. The first commit may contain the bugfix, and the second commit may contain the associated unit test. For commits related to different bugfixes or features, multiple PRs must be opened!

If your PR contains multiple commits but it makes more sense to have a single commit (imagine you forgot to modify a file, or you iterated on the same files multiple times), then you can either squash locally and force push, or ask your reviewer to squash your commits (commits merged all in once) or not before merging by adding and to: squash or to: rebase-and-merge.

Cherry picks

Cherry picks should always be done in a ascending branch order. For example v1.3.x > v1.4.x > master.

How to build locally

Please refer to Jenkins job

Development Tutorials

https://github.com/eclipse/capella/wiki/Tutorials