Implementing a code change

To start on a code change, make sure you have configured your environment to our standards and reviewed our acceptance criteria. This will make code review significantly easier and faster.

Each code change is applied against a specific repository. Depending on your task, you may need to make a change in multiple repositories. Follow these instructions for each one, and try to ensure your changes don't depend on each other, if feasible.

Please note that you will need to be connected to the University's network via VPN if you use a wireless connection or are off-campus. However, using VPN interferes with the virtual machine's network connection and will prevent you from viewing the site while it is on. You will need to connect whenever you need to run a clone, fetch, pull, or push command, or if you would like to access GitLab, and then you will need to disconnect.

Working on a code change

  1. Open up your command line interface and navigate to the directory you will be making the code change in. You can use graphical tools to perform these steps as well, but we have found it harder to manage exactly what goes into the build with graphical tools.
  2. Make sure you are on the latest version of the master branch, using the following command. Do not skip this step ever - it is much more difficult to review and apply patches that are from branches other than master, or that are from a very old version of master. git checkout master git fetch --all
  3. Choose a branch name for your work. The branch name should be WEB-{JIRA TICKET ID}_{YOUR USERNAME}. If you need to create multiple branches in the same repository for the same ticket, add additional information after your username, separating words with underscores. If your branch needs to be hotfixed onto the server, append "_hotfix" to the end. For example, to work on WEB-1000, one might create the branch "WEB-1000_jsmith".
  4. Create and checkout your branch using the following command - replace "[BRANCH]" with the branch name you picked above: git checkout -b [BRANCH]
  5. Work on your code change.
  6. Each time you reach a point at which you have added something new that works properly, you should commit it to your branch. It is up to the developer how to arrange this, but we would suggest that smaller commits are better than larger commits. Consider adding a new one each time the codebase does something new that works properly, such as creating a new database, adding a new menu hook, adding a new API function, etc.
  7. Before you commit, run the following command to check what code changes have been made: git diff
  8. Make sure that the acceptance criteria have been met for your code, and that you haven't included any debugging code (debugging code in files that aren't being committed can be left in).
  9. Add and commit the files with a good commit message. A good commit message follows the best practices of:
    • Starts with a subject line that is 50 characters or less, starts with a capital, does not end with a period, and uses the imperative mood for verbs (the imperative form is the one you use for your resume, in present third-person singular, e.g. "Fix typo in the documentation" or "Implement new load balancing handler").
    • Include, at the start of your subject line, the issue tracker ID followed by a colon and a space (e.g. "WEB-1000: Fix typo in the documentation").
    • Sometimes, the subject line is enough. If a person unfamiliar with the history of the project can tell why your commit is important just from the subject, leave it at that.
    • Otherwise, after the subject line, put a blank line, and then explain why you made this change (e.g. what bug is it fixing, what new feature does it offer). Discuss any caveats or known problems with the code, or any gotchas that somebody might need to know. Separate paragraphs with blank lines, and limit your text to 80 characters per line or less. Add bullet points by starting lines with hyphens or asterisks, and indenting other lines that are part of the same bullet.
    git add * # instead of *, you can select a specific file instead git commit -m 'WEB-1000: Implement new load balancing handler The previous load balancer was causing 404 pages for users, due to a memory leak issue. This new load balancer does not have that memory leak. Users previously using feature XYZ should be aware that this feature is slower in the new load balancer. Please migrate to using the new feature ZYX instead.'

Submitting a code change

  1. Once you have finished working on your ticket, you're ready to move on to submitting it for review.
  2. If the project includes test cases, run them and ensure they pass before submitting your code for review.
  3. If you haven't worked in the repository before, you'll need to add a remote server to the repository. This allows you to use your GitLab credentials to submit the change. Replace [PROJECT_NAME] with the name of the repository. Note that not all projects are namespaced under "webcms/", but almost all of them are. git remote add gitlab gitlab:webcms/[PROJECT_NAME]
  4. Push your branch up to GitLab. Replace [BRANCH] with the name of your topic branch. git push gitlab [BRANCH]
  5. Now you can logon to GitLab and prepare your merge request.
  6. Start by finding the repository you worked on, by using the filter on your dashboard.
  7. Click on "Merge Requests" on the left of the project page to open the Merge Requests list.
  8. Click the green button to "+ New Merge Request", at the top-right of your screen.
  9. For the Source branch, select the [BRANCH] that you just pushed.
  10. For the Target branch, make sure that the master branch is selected.
  11. Click "Compare branches".
  12. Review the differences between the two branches, to ensure that only the changes you wanted are included.
  13. Make sure the description represents your change completely.
  14. Assign it to another member of the team, and set the milestone to the next release.
  15. Submit the merge request.
  16. Move the JIRA ticket to "Code Review".

Reviewing a code change

  1. We encourage all developers to review code changes submitted by others (though only a gatekeeper can move a branch into master). If you have some time, feel free to look through merge requests and comment on them.
  2. Once you have submitted your code, encourage a teammate to review it as well.
  3. Make comments by logging into GitLab, viewing a merge request, and then either adding a comment to a specific line or to the general discussion.
  4. If you are happy with the code change and think it should be merged, make a discussion comment with "+1" in it.
  5. If you think it shouldn't be merged in its current state, add a discussion comment with "-1" in it. Please explain why you feel this change should not be merged.
  6. It is preferable if code changes have been +1'd by somebody other than the gatekeeper and the original submitter before being merged.
» Submit feedback
  • Developers
  • Getting Started
Back to top