cklist repo management

Repo management

Initial setup

• In each repo (e.g., front- and back-end), create a development branch in addition to the master.
  • All new feature development will be done as branches off development.
  • Master preserves the current production release.
• For team development, configure settings/branches on both development and master to protect these branches, as follows (requires administrator privileges on the repo):
  • Check Protect this branch.
  • Check Require pull request before merging.
  • Check Dismiss stale pull request approvals when new commits are pushed.
  • Check Require status checks to pass before merging.
  • Check Require branches to be up to date before merging.
  • Check Include administrators.

Starting work on new feature

• git checkout development
• Bring your local copy of development up to date: git pull origin development
• Create the new work branch: git checkout -b issue#xxx where xxx is the issue number in the repo. All work requires a corresponding issue.

Commits

• Include the following in the commit message:
  • Summary line: purpose of work; use active tense.
  • Why: intended to give others insight into the motivation for the changes.
  • What: high-level approach, technology, etc.
  • Editorials: identify & explain rationale for any adjustments to e.g., file or variable names.
  • Consequences: identify work that has to be done as a result of what was done in this commit. If work is outside the scope of the current issue, open a new issue to describe it & include a reference in this commit message.
  • Test results: summary if tests were done, anything that failed that needs continuing work within this issue branch or would be dealt with under a referenced (potentially new) issue.
  • Reference: list of issue numbers (e.g., #221) related to this commit.
  • Closes: list of issue numbers closed with the completion of work in this commit.

Start of work session (at least daily)

Bring your local version of development current, and rebase your issue#xxx branch on the current state of development, as follows:

• git checkout development
• git pull --rebase development
• git checkout issue#xxx
• git rebase development If there are conflicts, work through each one with the team to resolve them; see the following section. Commit each resolution. Repeat above steps.
• Use commits and git push origin issue#xxx to back-up incremental work to the repo, especially before taking breaks.

Integrating completed feature branch

• Push the feature branch into the GitHub repo: git push origin issue#xxx
• Create a pull request to the development branch on the GitHub repo.
• Review the pull request as a team:
  • Are the contents approved (design & code review)?
  • Can it be merged automatically? If conflicts are identified, the git merge process will suspend with a conflict error message. Resolve as follows:
  • git status will list the files in conflict. Discuss resolution with team members.
  • The developer of the issue branch implements the resolutions. Use git add (or git rm) to re-stage (or remove) each file with its resolution.
  • git rebase --continue to resume the rebase process… or abort the rebase and rollback as if it was never attempted with git rebase --abort. N.b.: Personal perspective: It seems more sensible to abort the rebase into development, have the developer rebase her local development and resolve the conflicts locally, and then push to the repo and issue a new pull request.

Integrating into production

When next version of app is ready to deploy:

• unlock the master, using branch protection settings in the repo.
• git checkout master
• git merge development
• git push origin master
• For back end, follow the heroku deployment steps.
• For front end, follow the browser template deployment steps or ember deployment steps.