Git Process for Code the Dream Practicums

In a practicum, a team of developers shares access to a single git repository. This can create problems. Several team members may change a given piece of code, with the result that conflicting changes are introduced. Students need to learn the process by which code is managed in a joint project, how to avoid merge conflicts, and how to resolve them if they occur. The process described below is recommended. Practicum mentors may choose to modify this as appropriate for their practicum.

Setup: Code the Dream

Someone from Code the Dream creates the practicum repository or repositories within the Code-the-Dream-School Github account. If a Github project is being used to manage the practicum, they will also create the corresponding project. Use of Github projects requires that practicum mentors and students be added to the Github Code-the-Dream-School organization, so if Github projects are being used they do that too. The practicum mentor (or mentors) are made administrators for the repostories and the project.

Setup: Practicum Mentor

The following is a recommendation, but project mentors may customize this as appropriate for the practicum. The mentor configures a the main branch of the repository so that only they, not the students, can push to that branch, and so that a pull request is required to push to the branch. The mentor also creates a dev branch. This is also configured with a branch protection rule, so that a push requires a pull request, the pull request must be approved, and the approval must come from someone other that the last pusher for that branch. It’s also a good idea to create a pull request template. The mentor then gives each student write access to the repostiory and the project. Each pull request should be associated with a work item in the management board (Github project or equivalent.)

(The process described below assumes that each practicum participant has write access to the repository. An alternative is for each student to fork the code. The flow in that case is similar.)

Setup: Student

Each student clones the project. They also get the dev branch as follows:

git fetch
git pull origin dev

Flow

Students who are not skilled in git should review these brief references:

Ideally, one would not have several team members working on the same files at the same time. But this is not always possible, so merge conflicts can occur. The process below describes how merge conflicts may be minimized, and how they can be resolved when they do occur. The developer works from the dev branch entirely, doing very little with the main branch. As code is added, it follows a triangular flow: The developer pushes a feature branch with new code or bug fixes, the code is merged into the dev branch, and then all developers pull the dev branch to get the latest version.

Practicum participants, here are the steps you follow:

git checkout dev
git pull origin dev (make sure you are up to date)
git checkout -b your-feature-name (Do not make changes to the main or dev branches. Note: If you forget, there are ways to save your changes and to get the master branch back the way it was. For example, if you have not committed changes, you can use git stash, then create the feature branch, then do git stash apply.) Teams adopt various rules as to the naming of feature branches. Sometimes you may be developing a feature that builds on a previous feature that has not been merged into dev. In that case, you create the new feature branch when the previous feature is the active branch.
Develop your feature.
Add and commit your changes.
Push your feature branch: git push origin feature-branch-name. This should be done periodically, even before you are done with your feature, so that you don’t lose your work.
Test your feature, including any automated testing if the project has it. Make any changes necessary to make the tests pass.
Commit and push your changes again.
git checkout dev (You need to merge in any changes that your colleagues have made in the meantime.)
git pull origin dev
git checkout your-feature-name
git merge dev (Now, at this point, if anyone has made changes to the same files you changed, you will need to resolve merge conflicts.)
Resolve merge conflicts, if any, and add and commit your changes.
Test again to make sure the merge conflict resolution did not break anything.
Push your changes
Do a pull request on github. The target of the pull request must be the dev branch.
A reviewer will review your code and may request changes.
If changes are needed, make them to the your-feature-name branch and test the result. Then add, commit, and push again. It is not necessary to create a new pull request, as your changes will be added to the existing pull request.
Once the reviewer(s) have approved the pull request, merge it into dev.
Time for a new feature branch!

A video explaining how to resolve merge conflicts is available here.

Periodically, when the dev branch is known to be stable, the mentor merges those changes into the main branch, and the application is deployed into production from there. Each student should learn how to do this deployment.

If the Dev Branch is Broken

If an unwise change is made and merged, the dev branch may be broken. In most cases, the developer that made the breaking change then does a bug fix in a new branch, and this is propagated to the dev branch via the process above. In rare cases, it may be necessary to revert a change. Git reverts are tricky. They should be performed or supervised by a mentor.