Contributing to Akka
- Sign the Akka Contributor License Agreement, we won't accept anything from anybody who has not signed it.
- Find-or-create a ticket in the issue tracker
- Assign that ticket to yourself
- Create a local branch with the following name format: wip-X-Y-Z where the X is the number of the ticket in the tracker, and Y is some brief keywords of the ticket title and Z is your initials or similar. Example: wip-2373-add-contributing-md-√
- Do what needs to be done (with tests and docs if applicable). Your branch should pass all tests before going any further.
- Push the branch to your clone of the Akka repository
- Create a Pull Request onto the applicable Akka branch, if the number of commits are more than a few, please squash the commits first.
- Change the status of your ticket to "Test"
- The Pull Request will be reviewed by the Akka committers
- Modify the Pull Request as agreed upon during the review, then push the changes to your branch in your Akka repository, the Pull Request should be automatically updated with the new content.
- Several cycles of review-then-change might occur.
- Pull Request is either merged by the Akka committers, or rejected, and the associated ticket will be updated to reflect that.
- Delete the local and remote wip-X-Y-Z
Akka utilizes peer code reviews to streamline the codebase, reduce the defect ratio, increase maintainability and spread knowledge about how things are solved.
Core review values:
- Rule: The Boy Scout Rule
- Why: Small improvements add up over time, keeping the codebase in shape.
- Rule: Don't Repeat Yourself
- Why: Repetitions are not maintainable, keeping things DRY makes it easier to fix bugs and refactor, since you only need to apply the correction in one place, or perform the refactoring at one place.
- Rule: Feature tests > Integration tests > Unit tests
- Why: Without proving that a feature works, the code is only liability. Without proving that a feature works with other features, the code is of limited value. Without proving the individual parts of a feature works, the code is harder to debug.
Akka uses Scalariform to enforce some of the code style rules.
For external contributions of entire features, the normal way is to establish it as a stand-alone feature first, to show that there is a need for the feature. The next step would be to add it to Akka as an "experimental feature" (in the akka-contrib subproject), then when the feature is hardened, well documented and tested it becomes an officially supported Akka feature.