Until the move to GitHub we used Gerrit and it’s clearly defined review process for development. With the move to GitHub that has changed, but right now there is no clear decision yet as how we want to continue.
While the overall workflow shouldn’t be a problem (fork, hack, create pull request), there are some questions to answer. To do that, we’d like to draw from your combined knowledge and preferences.
Development workflow - what is clear so far
- Changes against packages are done in forks.
- For packages that are part of monolithic repositores (“development collections” as we call them), pull requests need to be done against those, not against the individual (read-only) package repositories.
- Merges can be done by any member of the Neos organisation on GitHub (which should be everyone in the Neos team)
- To be considered merge-ready, a change must pass the existing tests and have been reviewed by some people. Basically the rules we had when using Gerrit still apply, we want clean and working code.
- As soon as something is merged, the read-only repositories are updated automatically (GitHub webhook to our Jenkins)
- Commit messages should still follow the established rules we have now
Q: Branch maintenance
Here comes the first open question… How do we maintain branches?
Until now we used a Releases footer in commit messages to record where a change needs to be applied (e.g. Releases: master, 2.0, 2.1). We then cherry-picked those changes to all those branches as needed, either using the corresponding button in Gerrit or the command line (in case of conflicts).
This was easy to do, but has the drawback that for keeping an overview of the status of those changes, we need to rely on Gerrit (it has “included in” information for changes) and the “merged changes overviews” for Flow and Neos. And it isn’t really an established way to maintain branches in the Git world.
An alternative would be to create any bugfix or change that needs to go into an older branch for the “lowest” (oldest) maintained branch that is affected. As bugs are fixed in those branches, we can do (occasional) merges into the newer branches and a) be sure changes are merged and b) clearly see the state of affairs by looking at the Git tree.
Q: Pull request creation & handling
Depending on the decision for branch handling we know how to create pull requests (oldest branch first or master first). When creating a pull request, in the easiest scenario it is just one commit. In this case, write the commit message following the established rules, since it will become the message on the pull request (and the commit message of the resulting merge commit). If more than one commit are in one pull request, make sure to give the pull request a message that follows the established rules - that could be done by copying the message of the first commit, or by writing a proper one from scratch.
There is one more decision to take, though: how to merge pull requests.
If a PR is just a single commit, we can of course just merge via the GitHub UI. In case a pull request went through a more or less intensive review and has some commits to fix things, we have options to choose from:
- One is to use the GitHub UI as well and keep that history (if nothing else, it can serve as an example of how we work and what makes a good pull request).
- Another option is to squash during merge. This keeps history more linear and can “hide stupid things that had to be fixed”, but might be more work.
- The third option is to amend as we used to do with Gerrit and force push the branch the PR is created for. Testing has shown this works fine with comments on pull requests etc. Not the “pure form” of working with git, but might be some “middle ground”.
All that being said: I am looking forward to your input!