CONTRIBUTING

# Contributing to Sirius

Thanks for your interest in this project.
In this document, you will find the various rules to contribute to this project.
The project will be maintained in english and everything will reside in a single Git repository.

## Project description

Eclipse Sirius enables the specification of a modeling workbench in terms of
graphical, table or tree editors with validation rules and actions using
declarative descriptions.

- http://www.eclipse.dev/sirius
- https://projects.eclipse.org/projects/modeling.sirius

## Planning

We are working in iteration of 8 weeks.
The first six weeks are used to improve the product with new features and bug fixes.
After that, we have a period of two weeks during which we work on non-technical details of the release (documentation, communication, etc) and some technical debts.

## Git

Development is done on the branch master, and all changes must first go through a pull request.
Obviously, contributors are free to do whatever they want on their local clone(s) and Github forks, the rules above only apply to commits and branches pushed into the official repository.

The work in progress from the official contributors can be visible on their dedicated branches.
These branches are named using the following naming convention:

```
three_letters_identifying_the_contributor/kind_of_work/description
```

You could thus find in our repository branches such as:

- `sbe/fix/diagram-related-issue`
- `pcd/enh/new-feature-the-view-dsl`
- `gco/doc/architectural-documentation`

We are working with a linear history and all pull requests are rebased on top of the master branch in order to be integrated.
Contributors are free to create as many commits as they want in the branch of their pull requests, the contributions will be squashed to one or two commits when it will be integrated.

## Commit messages formatting

We are using the following format for all our Git messages:

```
[XXXX] Short description

Longer description if needed, explaining the reasons of the change and its
impact, not paraphrasing the patch. The description should use wrapped line.

Bug: https://github.com/eclipse-sirius/sirius-components/issues/XXXX
Signed-off-by: Author name <author email>
```

You should always mention the numeric bug id at the start of the first line (e.g. [1247]).
For the few cases where a commit is not directly related to an issue, use a tag like [releng], [doc] or [cleanup]...
Look for previously used tag before creating a new one.

## Changelog

All contributions should be mentioned in the file `CHANGELOG.adoc`.
If a long description is necessary to provide additional details for a commit, it is necessary to provide those details in the changelog.
Most of our commit messages do not contain a long description since those details are written in the changelog.

Contributions which have a visual impact should try to provide screenshots showing the changes.
These images referenced from the changelog should be added in `doc/images`, not in the top-level directory.

## Release

We are using a calendar versioning approach for our tags and releases.
We are performing a new major release every two months following the given planning:

- Week 1 to 4: development of new features and bug fixes
- Week 5: First release candidate (RC1)
- Week 6: Homologation of the first release candidate and development of bug fixes
- Week 7: Second release candidate (RC2)
- Week 8: General availability (GA)

The GA version will always end with a `.0` such as `v2025.8.0` or `v2025.10.0`.
Those versions have been extensively tested by the development team during the homologation phase.
On top of this release, we will perform the release of various milestones with number like `v2025.8.1` (the first milestone after `v2025.8.0`), `v2025.8.2`, etc.
Milestones are not maintenance versions of the previous GA but instead intermediate versions towards the next stable release.
As such, they will include breaking changes that are documented in the file CHANGELOG.adoc at the root of the Git repository.
The release candidate will use the same naming strategy as regular milestones.

For each release, a Github release will be performed with the following strategy.

In case we are publishing a new GA version such as `v2025.10.0`, a new Github release will be created with the name of the tag (i.e. `v2025.10.0`), this Github release will be identified as the latest stable release and use the previous GA version (i.e. `v2025.8.0`) as its previous release.
This previous release is used to create the changelog of the Github release.

If we are publishing a regular milestone, we will use the following pattern for the Github release `v2025.10.3 - Milestone 3 for v2025.12.0` and we will use either the last stable release (in case of a `.1` milestone) or the latest milestone as the previous version to create the Github release changelog.
Those releases will be identified as "pre-release" in Github to distinguish them from the stable releases.
If will help consumers understand that those milestones will not provide the same level of maturity as stable releases since the entire homologation process is not performed.

Finally, if we are publishing a release candidate, we will instead rely on the pattern `v2025.10.5 - RC1 for v2025.12.0` and we will use the latest milestone as the previous version to create the changelog.

In the end, our Github releases should contain releases such as these ones:

[cols="1,2,1", options="header"]
|====
| Tag | Title | Previous version
| `v2025.12.0` | `v2025.12.0` | `v2025.10.0`
| `v2025.12.1` | `v2025.12.1 - Milestone 1 for v2026.1.0` | `v2025.12.0`
| `v2025.12.2` | `v2025.12.2 - Milestone 2 for v2026.1.0` | `v2025.12.1`
| `v2025.12.3` | `v2025.12.3 - Milestone 3 for v2026.1.0` | `v2025.12.2`
| `v2025.12.4` | `v2025.12.4 - RC1 for v2026.1.0` | `v2025.12.3`
| `v2025.12.5` | `v2025.12.5 - RC2 for v2026.1.0` | `v2025.12.4`
| `v2026.1.0` | `v2026.1.0` | `v2025.12.0`
|====

## Developer resources

Information regarding source code management, builds, coding standards, and
more.

- https://projects.eclipse.org/projects/modeling.sirius/developer

The project as a whole maintains the following source code repositories

- https://github.com/eclipse-sirius/sirius-web
- https://github.com/eclipse-sirius/sirius-components
- https://github.com/eclipse-sirius/sirius-emf-json
- https://git.eclipse.org/c/sirius/org.eclipse.sirius.git
- https://git.eclipse.org/c/sirius/org.eclipse.sirius.legacy.git

This particular sub-project of Sirius, uses GitHub Issues to track ongoing development and issues.

- Search for issues: https://github.com/eclipse-sirius/sirius-components/issues
- Create a new report: https://github.com/eclipse-sirius/sirius-components/issues/new/choose

Be sure to search for existing bugs before you create another one.
Remember that contributions are always welcome! There are many ways to
contribute, from entering high quality bug reports, to contributing
code or documentation changes. For a complete guide, see the [How to
Contribute](http://wiki.eclipse.org/Sirius/Contributor_Guide) page on
the team wiki. For further questions about contributing to Sirius,
please send a mail to sirius-dev@eclipse.org.

## Eclipse Contributor Agreement

Before your contribution can be accepted by the project team contributors must
electronically sign the Eclipse Contributor Agreement (ECA).

- http://www.eclipse.org/legal/ECA.php

Commits that are provided by non-committers must have a Signed-off-by field in
the footer indicating that the author is aware of the terms by which the
contribution has been provided to the project. The non-committer must
additionally have an Eclipse Foundation account and must have a signed Eclipse
Contributor Agreement (ECA) on file.

For more information, please see the Eclipse Committer Handbook:
https://www.eclipse.org/projects/handbook/#resources-commit

## Contact

Contact the project developers via the project's "dev" list.

- https://accounts.eclipse.org/mailing-list/sirius-dev