Development Process

Every project that's part of that Vert.x stack (that's everything under the vert-x3 organisation in GitHub) must follow this process.

The main aims of the development process are:

• To ensure a high quality of code in official Vert.x repositories
• To provide visibility to the community and the public in general about development.

Here is the process:

• All contributors must sign the Eclipse CLA.
• All development work [1] is carried out in a repository under the Vert-x3 organisation. If you are starting a completely new project ask an administrator to create an empty repository for you.
• For any changes > 10 lines or so, do not work directly on a master branch. master branches should never be a work-in-progress, they should be always maintained in a state that we are happy for users to run in production.
• For small changes < 10 lines or so (e.g. correcting typos, small changes to configuration and such-like) you can make those changes directly on a master branch.
• Issue related to a component must have its milestone set, e.g, a bug fix on vertx-core has for milestone 3.5.1...
• Issue irrelevant to the changelog of the component shall have an invalid label and no milestone set, e.g questions
• When doing an initial work on a new project, it's a convention to do that initial work on a branch named initial-work.
• If you've done any work, push your work branch at least once a day. It doesn't matter if it's not finished. It doesn't matter if it doesn't compile. Pushing your work serves two main purposes:
  • It provides visibility to the other developers, and to the wider community about the approach you are taking. Other developers can make comments on commits and discuss progress. It avoids situations where a developer has spent 2 months working on something behind closed doors before presenting it, only to find out it's taken a completely wrong approach. If you don't push the assumption will be no coding is going on.
  • It provides a backup.
• After working on your work branch, when you think your code is ready to be merged to master, you need to make sure it meets the following criteria:
  • It must adhere to the project code style guidelines.
  • There must be very good test coverage that covers all functionality.
  • The public interface(s) of the component must have JavaDoc that can be used by the docgen tool to generate manual documentation [This requirement won't come into action until docgen is complete]
  • New projects must provide a README.md which, at the least, gives an overview of the component.
  • You would be happy to personally use your work in an application upon which your livelihood depended.
• If you are happy that the work meets the above criteria then submit a pull request against the master branch and drop an email on vertx-dev@googlegroups.com to ask another developer to review it (or ask them directly).
• The PR must be reviewed by at least one other developer. Other developers are welcome to make comments on the PR too. The review should be carried out by placing comments on the PR in GitHub, not by sending private emails or other means. This provides visibility and provides a public record.
• Review comments will probably require further changes to the code before the PR is accepted. This is completely normal. Do not expect PRs to be accepted without further changes. Make those changes and tell the reviewer by adding a comment on the PR that you have made them and are ready for the changes to be reviewed (e.g. @joebloggs hey I made those changes we discussed, can you take a look again?). Do not expect the reviewer to know when you have made any further changes and are ready to have them reviewed without prompting them first.
• Repeat the above to and fro until there is concensus the work is ready to be merged into master. Once that point is reached, it can be merged.
• Concensus is always preferable, but if concensus on an approach cannot be reached, the Project Lead should decide on which approach to take.
• The process is fair and is applied to every developer, without exception.

[1] With the exception of work on vertx-core which is carried out in the Eclipse Vert.x Project and must additionally conform to the Eclipse Development Process.