Repository navigation
GitHub Procedures
This guide will detail the workflow for a GitHub repository. Follow this guide to make sure that you are properly commiting and pushing to the correct branches in the Development repo. If you are not familiar with git, please visit this page.
The workflow consists of three phases: Before Coding, Coding, and After Coding. All of these need to be followed every time you work on the project.
Every time you start working on a project, you should open up a terminal (or Git Bash, etc. on Windows) to your working directory. First of all, you need to make sure that you are on the correct development branch. Next, before doing any coding, type the following command:
git pull
This will make sure that you are working with the latest code. If someone else made any changes since you worked on the branch, those changes will be added. Next, you need to fix any merge conflicts. If you are unsure about some code in the merge that you did not make, consult with the creator of the code (You can find out who wrote the code by checking the commit messages or checking the git blame).
DO NOT work on the code until you have fixed any and all merge conflicts.
After pulling the latest code and fixing any merge conflicts, you can commence with coding.
Surprisingly enough, this is the phase during which you code. Make sure to follow the coding standards when doing so. After completing a major feature, commit your changes.
When you are done coding, run git push to push your changes to the GitHub server. Remember to never push (or commit) any code that does not work or breaks part of the project. More often than not, this is all you need to do after coding.
If you are completely finished with an assignment/feature, then it is time to push to the master branch. Before merging to the master branch, first make sure, to the best of your ability, that everything works. Half-working features should NOT be merged to the master branch. If your assignment, for example, was only to complete part of a feature, then it is not time to merge it to the master branch. It is best to consult with the manager and/or other developers before merging to the master branch.
When merging to the master branch, make sure to use the --squash argument in your merge statement to ensure that your merge is listed as a single commit - this keeps the commit statements in the master branch nice and clean. After merging, you need to take care of merge conflicts, updating the API Documentation, updating the change log, and emailing the team about the change. It is best to have the API documentation, etc. prepared beforehand so that the merge is as smooth as possible.
Check the API Documentation and Change Log sections below for more information on those topics. When emailing the team about the change, make sure to include the AP documentation and change log changes you added. When the team members get an email about an update on the master branch, they will need to merge the master branch into their respective development branches to ensure that their code is up-to-date. Your API documentation and change log updates should contain enough information so that any merge conflicts your colleagues run into can be easily handled.
There are two important rules when it comes to commits:
- Never commit code with known bugs.
- Be detailed but concise in your commit messages.
These two guidelines reinforce the principle that* every commit should be meaningful*.
The concept of branches in git is extremely important. Make sure you know how to work with git branches.
When starting work on a new feature/assignment, you should make a branch for that assignment (if one is not already made). This should be branched off of the current master branch and named with a Dev prefix. These development branches are where most of the work will occur.
Try to name your branch using a single word, if possible. For example, DevHeader or DevBots.
The master branch is essentially the staging area for the production repo/live site. It should be a working version of the project with the latest new features. This is where new features will be pushed once they are completed.
The production repo has a simple purpose - to mirror the code that is currently on the live site. No development should ever be done in this branch. Only the admins will have push permissions for this repo.
We will use the GitHub Wiki for all non-theoretical documentation. The documentation will be located in the Development repo; the Production repo will contain purely the code of the live site.
All functions/classes/files that are designed to be multi-purposed and reusable should be documented. Whenever a change is made to one of these documented aspects of the project, make sure to update the documentation as well.
The documentation should be such that another developer can read the documentation on a file, class, or function and know everything he/she needs to know without having to look at the actual code. Be as specific as possible, but also be concise.
Note: The documentation should only be changed after the new code is pushed to the master branch.
There will be a Wiki page for change logs on the master branch. Every time a new feature (or set of features) is pushed into the master branch, the change log should be updated. Sometimes, this might consist of just copy-pasting the commit message. However, sometimes your changes might be more impactful - for instance, maybe you changed a function everyone uses. The change log needs to have instructions for other developers on how to update their code accordingly.
Every time new code is pushed to the master branch, the master branch version number should be updated in accordance to the significance/quantity of the new code. Consult with the manager if you are unsure.