We follow the standard GitHub fork & pull approach to pull requests. Just fork the official repo, develop in a branch, and submit a PR!
You're always welcome to submit your PR straight away and start the discussion (without reading the rest of this wonderful doc, or the README.md). The goal of these notes is to make your experience contributing to Apache Pekko as smooth and pleasant as possible. We're happy to guide you through the process once you've submitted your PR.
If you have questions about the contribution process or discuss specific issues, please interact with the community using the following resources.
- GitHub discussions: for questions and general discussion.
- Pekko dev mailing list: for Pekko development discussions.
- GitHub issues: for bug reports and feature requests. Please search the existing issues before creating new ones. If you are unsure whether you have found a bug, consider asking in GitHub discussions or the mailing list first.
Depending on which version (or sometimes module) you want to work on, you should target a specific branch as explained below:
main– active development branch of Pekko Persistence Cassandrarelease-x.y– maintenance branch of Pekko Persistence Cassandra x.y.z
These guidelines apply to all Pekko projects, by which we currently mean both the apache/pekko repository, as well as any plugins or additional repositories.
These guidelines are meant to be a living document that should be changed and adapted as needed. We encourage changes that make it easier to achieve our goals efficiently.
The steps below describe how to get a patch into the main development branch (main).
The steps are exactly the same for everyone involved in the project, including the core team and first-time contributors.
- To avoid duplicated effort, it might be good to check the issue tracker and existing pull requests for existing work.
- If there is no ticket yet, feel free to create one to discuss the problem and the approach you want to take to solve it.
- Fork the project on GitHub. You'll need to create a feature-branch for your work on your fork, as this way you'll be able to submit a pull request against the mainline Pekko.
- Create a branch on your fork and work on the feature. For example:
git checkout -b custom-headers-pekko-http- Please make sure to follow the general quality guidelines (specified below) when developing your patch.
- Please write additional tests covering your feature and adjust existing ones if needed before submitting your pull request.
- Use the
verifyCodeStylesbt task to ensure your code is properly formatted and includes the proper copyright headers.
- Once your feature is complete, prepare the commit following our Creating Commits And Writing Commit Messages. For example, a good commit message would be:
Adding compression support for Manifests #22222(note the reference to the ticket it aimed to resolve). - If it's a new feature or a change of behavior, document it on the docs. When the feature touches Scala and Java DSL, document both the Scala and Java APIs.
- Now it's finally time to submit the pull request!
- Please make sure to include a reference to the issue you're solving in the comment for the Pull Request, as this will cause the PR to be linked properly with the issue. Examples of good phrases for this are: "Resolves #1234" or "Refs #1234".
- If you are a first time contributor, a core member must approve the CI to run for your pull request.
- For non-trivial changes, you will be asked to sign the CLA if you have not done so before.
- Now, both committers and interested people will review your code. This process ensures that the code we merge is of the best possible quality and that no silly mistakes slip through. You're expected to follow-up on these comments by adding new commits to the same branch. The commit messages of those commits can be more loose, for example:
Removed debugging using printline, as they all will be squashed into one commit before merging into the main branch.- The community and core team are really nice people, so don't be afraid to ask follow-up questions if you didn't understand some comment or would like clarification on how to continue with a given feature. We're here to help, so feel free to ask and discuss any questions you might have during the review process!
- After the review, you should fix the issues as needed (pushing a new commit for a new review, etc.), iterating until the reviewers give their approval signaled by GitHub's pull-request approval feature. Usually, a reviewer will add an
LGTMcomment, which means "Looks Good To Me".- In general, a PR is expected to get 2 approvals from the team before it is merged. If the PR is trivial or under exceptional circumstances (such as most of the core team being on vacation, a PR was very thoroughly reviewed/tested and surely is correct), a single LGTM may be fine as well.
- If the code change needs to be applied to other branches as well (for example, a bugfix needing to be backported to a previous version), one of the team members will either ask you to submit a PR with the same commits to the old branch or will do this for you.
- Follow the backporting steps below.
- Once everything is said and done, your pull request gets merged 🎉 Your feature will be available with the next "earliest" release milestone (i.e. if backported so that it will be in release x.y.z, find the relevant milestone for that release). Of course, you will be given credit for the fix in the release stats during the release's announcement. You've made it!
The TL;DR; of the above very precise workflow version is:
- Fork Pekko
- Hack and test on your feature (on a branch)
- Document it
- Submit a PR
- Sign the CLA if necessary
- Keep polishing it until getting the required number of approvals
- Profit!
Note: Github Actions runs all the workflows for the forked project. We have filters to ensure that each action effectively runs only for the
apache/pekko-persistence-cassandrarepository, but you may also want to disable Github Actions entirely in your fork.
Backport pull requests such as these are marked using the phrase for validation in the title to make the purpose clear in the pull request list.
They can be merged once validation passes without additional review (if there are no conflicts).
Using, for example: current.version 2.5.22, previous.version 2.5, milestone.version 2.6.0-M1
- Label this PR with
to-be-backported - Mark this PR with Milestone
${milestone.version} - Mark the issue with Milestone
${current.version} git checkout release-${previous.version}git pull- Create wip branch
git cherry-pick <commit>- Open PR, target
release-${previous.version} - Label that PR with
backport - Merge backport PR after validation (no need for full PR reviews)
- Close issue.
The tests rely on a Cassandra instance running locally on port 9042. A docker-compose file is
provided in the root of the project to start this with docker compose up -d cassandra
For a pull request to be considered at all, it has to meet these requirements:
- Regardless if the code introduces new features or fixes bugs or regressions, it must have comprehensive tests.
- The code must be well documented as per the existing documentation format (see the 'Documentation' section below).
- The commit messages must properly describe the changes. See further below.
- A pull request must be linked to the issue it aims to resolve in the PR's description (or comments). This can be achieved by writing "Fixes #1234" or similar in PR description.
- Licensing rules:
- Existing files with copyright statements must leave those copyright statements intact
- New files should have an Apache license header instead. For an example of this, see this file.
pekko-persistence-cassandra is currently documented in the README.md. If we were to provide more extensive documentation, paradox would be the tool of choice. See the Apache Pekko Connectors project for an example.
All the external runtime dependencies for the project, including transitive dependencies, must have an open source license that is equal to, or compatible with, Apache 2.
This must be ensured by manually verifying the license for all the dependencies for the project:
- Whenever a committer to the project changes a version of a dependency (including Scala) in the build file.
- Whenever a committer to the project adds a new dependency.
- Whenever a new release is cut (public or private for a customer).
Which licenses are compatible with Apache 2 are defined in this doc, where you can see that the licenses that are listed under Category A automatically compatible with Apache 2, while the ones listed under Category B needs additional action:
Each license in this category requires some degree of reciprocity. This may mean that additional action is warranted in order to minimize the chance that a user of an Apache product will create a derivative work of a differently-licensed portion of an Apache product without being aware of the applicable requirements.
Each project must also create and maintain a list of all dependencies and their licenses, including all their transitive dependencies. This can be done in either in the documentation or in the build file next to each dependency.
It is ok to work on a public feature branch in the GitHub repository. Something that can sometimes be useful for early feedback etc. If so then it is preferable to name the branch accordingly. This can be done by either prefix the name with wip- as in ‘Work In Progress’, or use hierarchical names like wip/.., feature/.. or topic/... Either way is fine as long as it is clear that it is work in progress and not ready for merge. This work can temporarily have a lower standard. However, to be merged into main branch it will have to go through the regular process outlined above, with Pull Request, review etc..
Also, to facilitate both well-formed commits and working together, the wip and feature/topic identifiers also have special meaning. Any branch labelled with wip is considered “git-unstable” and may be rebased and have its history rewritten. Any branch with feature/topic in the name is considered “stable” enough for others to depend on when a group is working on a feature.
Follow these guidelines when creating public commits and writing commit messages.
-
If your work spans multiple local commits (for example; if you do safe point commits while working in a feature branch or work in a branch for long time doing merges/rebases etc.) then please do not commit it all but rewrite the history by squashing the commits into a single big commit which you write a good commit message for (like discussed in the following sections). For more info read this article: Git Workflow. Every commit should be able to be used in isolation, cherry picked etc.
-
First line should be a descriptive sentence what the commit is doing, including the ticket number. It should be possible to fully understand what the commit does—but not necessarily how it does it—by just reading this single line. We follow the “imperative present tense” style for commit messages (more info here).
It is not ok to only list the ticket number, type "minor fix" or similar. If the commit is a small fix, then you are done. If not, go to 3.
-
Following the single line description should be a blank line followed by an enumerated list with the details of the commit.
-
Add keywords for your commit (depending on the degree of automation we reach, the list may change over time):
Review by @gituser- if you want to notify someone on the team. The others can, and are encouraged to participate.
Example:
Add eventsByTag query #123
* Details 1
* Details 2
* Details 3
The project uses scalafmt to ensure code quality which is automatically checked on
every PR. If you would like to check for any potential code style problems locally you can run sbt checkCodeStyle
and if you want to apply the code style then you can run sbt applyCodeStyle.
Throughout the history of the codebase various formatting commits have been applied as the scalafmt style has evolved over time, if desired one can setup git blame to ignore these commits. The hashes for these specific are stored in this file so to configure git blame to ignore these commits you can execute the following.
git config blame.ignoreRevsFile .git-blame-ignore-revs