If this is your first time contributing to an Eclipse Foundation project, you'll need to sign the Eclipse Contributor Agreement.
- Create an account on dev.eclipse.org
- Open your Account Settings tab, enter your GitHub ID and click Update Account
- Read and sign the ECA
- Your git commits must be signed off
- Use the exact same email address for your Eclipse account, your commit author, and your commit sign-off.
Search the issue tracker for a relevant issue or create a new one.
Fork the repository in GitHub and make changes in your fork.
Please add a description of your changes to the draft release notes.
Finally, submit a pull request.
Details on working with GitHub for Eclipse Collections is located at the Wiki.
The Eclipse Collections build requires below as dependencies.
- Java 1.8
- Maven 3.1.0+
The Eclipse Collections build performs code generation to create primitive collections. Run the full build once before opening your IDE.
$ mvn install -DskipTests=true
Now you can open the project in your IDE and it won't complain about missing files. You'll be able to use the IDE to perform incremental builds and run tests. You should rarely need to run the maven build, except when:
- you want to force a clean build
- you work on JMH tests
- your changes affect code generation
- you want to see if your changes will pass the same builds that GitHub Actions runs
Eclipse Collections version numbers follow Semantic Versioning. This means we increment the major version when we make incompatible API changes. This includes any changes which
- break binary compatibility
- break source compatibility
- break serialization compatibility
Normally, collections will have the same serialized form across major releases, indefinitely. But if we have to break serialization for some reason, it will be in a major release. Eclipse Collections includes a suite of serialization tests to prevent accidental changes.
While preparing a minor release, the master branch won't contain any compatibility breaking changes. Feel free to work on major, compatibility-breaking changes whenever you'd like. However, if you submit a pull request to master while we're preparing a minor release, you'll have to be patient and you'll need to rebase your changes once the release is complete.
Eclipse Collections follows a coding style that is similar to Google's Style Guide for Java, but with curly braces on their own lines. Many aspects of the style guide are enforced by CheckStyle, but not all, so please take care.
$ mvn clean install checkstyle:check findbugs:check --projects "!scala-unit-tests,!jmh-scala-tests,!jmh-tests" -DskipTests=true
Avoid changing whitespace on lines that are unrelated to your pull request. This helps preserve the accuracy of the git blame view, and makes code reviews easier.
- Use the imperative mood as in "Fix bug" or "Add feature" rather than "Fixed bug" or "Added feature"
- Mention the GitHub issue when relevant
- It's a good idea to follow the advice in Pro Git
- Sign-off your commits using
git commit --signoffor
git commit -sfor short
Excessive branching and merging can make git history confusing. With that in mind
- Squash your commits down to a few commits, or one commit, before submitting a pull request
- Rebase your pull request changes on top of the current master. Pull requests shouldn't include merge commits.
Submit your pull request when ready. Three checks will be kicked off automatically.
- IP Validation: Checks that all committers signed the Eclipse CLA and signed their commits.
- Continuous integration: GitHub Actions that run JUnit tests, CheckStyle, and FindBugs.
- The standard GitHub check that the pull request has no conflicts with the base branch.
Make sure all the checks pass. One of the committers will take a look and provide feedback or merge your contribution.
That's it! Thanks for contributing to Eclipse Collections!