Feature Branch Workflow with Github

The Vapor team decides to adopt a "feature branch" workflow using git. A more detailed explanation of this workflow is available here, and here are a few take-aways.

Take-aways

The "master" branch:

• The "master" branch is always in a "ready to build" state.
  • This means there is no compilation errors, nor warnings stemmed from VAPOR.
    • As of July 2018, we decide to target warning free on two platforms: macOS and Ubuntu Linux. The reason is that all VAPOR team members have easy access to these two platforms.
  • There should also be no debugging statements, nor code being commented out (i.e., only comments explaining the program is allowed).
• Anyone could/should start from the "master" branch to develop a new feature.

The feature/fix branches

• A new feature goes into a feature branch: the branch name identifies the issue that is being fixed (ie a branch that fixes issue #2273 may be named 'issue2273'.
• An issue fix goes into a feature branch too; the name of that branch should be issue_xxx where xxx is the issue number.
• This feature branch is merged into "master" only if the new feature is complete and passed all necessary tests, and the code is cleaned to comply with the VAPOR coding convention.
• It is the responsibility of the author of this feature branch to resolve any merge conflicts.
• This feature branch should be deleted once merged into the "master" branch.

The release tag

• A release tag is applied on the master branch once a release decision is made.
• This source code at this release state is also made available on Github's code release page.

Use the "Pull Request" feature of Github to ease code review.

• We have decided to use pull requests provided by Github to bring code from feature branches back to the master branch.
• Here is a list of steps for a "pull request"
  • Assume an issue, #123, shows up on Github, and a developer is going to fix it.
  • Starting from the latest master branch, this developer creates a bug fix branch named issue_123.
  • Once this issue is resolved, the developer pushes branch issue_123 back to Github.
  • This developer then submits a "pull request" on the Github web interface:
    • Under the "Pull request" tab on Github, click the green button "New pull request."
    • Select "issue_123" in the "Compare" box.
    • Then compare the two branches, resolve potential conflicts, and then submit a pull request.
    • In the comments section reference the issue number by typing "#123"
  • Other developers review the pull request, and merge it when appropriate. The branch issue_123 is deleted after a successful merge.

Best Practices:

Large pull requests with lots of files impacted are difficult to review. A few things that will make this workflow run smoother:

1. Always generate a GIT "issue" for any branches created. Don't simply create a new branch without an issue associated with it. Follow the naming convention issue_xxx.
2. Stay focused in the branch. Do not make changes that are not relevant to the associated issue. If you feel the need to make changes that aren't necessary for the specific issue (e.g. house cleaning) generate a new issue & branch specifically for that task.
3. Resist the urge to change file names needlessly. These are difficult to track. If you do feel compelled to rename files, create a issue/branch for this purpose.