Home
This document serves as a compilation of procedures that will be routinely used by developers and maintainers of the projects used in this semester of SWEN 670 Capstone.
This document utilizes GitHub exclusively to handle version control, repository management, and automatic pipelines. Version control and repository management is handled using the Git system. The pipelines are formed using GitHub Actions, which allows a developer to define a set of actions that should occur in response to a repository event.
Repository: The entirety of a project and the project’s history. This is normally stored in a “.git/” folder on your local machine.
Branch: A version of a repository that represents an independent line of development.
Remote: The remote repository is a Git repository that’s hosted on the internet instead of on your local machine. It is through the remote that developers can share their code and collaborate.
Commit: An action that saves staged changes to the local repository. Files can be removed from the staging area if they are not relevant to a commit. Each commit is a sort of snap shot of the state of the staged files that a developer can go back to at any time.
Push: An action that copies the commit history on a local repository to the remote repository.
Pull Request: A request for reviewers to look at the changes a developer has made and ensure that they are functional and understandable before merging the changes to a base branch.
Merge: An action that combines the contents of one branch into another. In most cases, it will be combining changes from a feature branch into the developer branch, or changes from the developer branch into the main branch.
Worku, A., Setiawan, M., Johnson, R. (2021, September 10). Captsone Project Management System (CaPPMS) & DevSecOps Infrastructure: Deployment and Operation Guide (Runbook). University of Maryland Global Campus.
Baker, J. (2021, March 31). Feature branching using feature flags - dzone devops. dzone.com. Retrieved January 13, 2022, from https://dzone.com/articles/feature-branching-using-feature-flags-1
The GitHub repository will consist of 3 major types of branches in order to keep new developments and features organized while maintaining the functionality of each release.
Main Branch: This branch contains operational code that can be released as a working version of the project. It does not have to include all the features that have been planned, and the project lead can decide when the project is in a good state to be merged into this branch. Generally, if a demo of the project is requested, the latest version in the Main Branch will be shown. In our use case, the repository admins/DSO team are the only personnel that is able to merge from other branches into the Main Branch.
Development Branch: This branch generally contains operational code, and serves as a staging environment in which any new features will be tested in order to establish their effects before being allowed to merge into the Main Branch. Code merged into the Developer Branch should work as intended in isolation without errors. As such code merged into the Developer Branch should be reviewed beforehand. The reviewer ideally should be the lead developers of each team and should walk through the changes with the original developer before merging.
Feature Branch: This is a type of branch that developers will create to address a specific feature or set of features of the project. This can entail adding new functionality or fixing existing faulty functionality. Generally, the name of the Feature Branch will reflect the goal of the task. When the developer is finished making the desired changes, they will initiate a pull request, in which a maintainer of the Git repository will review the code to be merged in order to enforce programming practices and limit the number of bugs introduced into the project.
Navigate to https://desktop.github.com/ and download the desktop client for your operating system.
Once you’ve installed the desktop client, select “Clone a repository from the Internet”. If you’ve not yet signed in to your GitHub account through the client, do so first.
Figure 1. GitHub Client Sign-in Page
Once you’ve signed in, find the repository for your project under the “umgc” organization, then select it. The string in the “Local path” text field will be where your local repository is saved. If you are satisfied with this location, select the “Clone” button.
Figure 2. Clone Repository Page
To get started with development, begin by creating a Feature Branch. This branch should be named based on the changes you’re planning, so ensure the name is descriptive enough that you know what you were working on in this branch. This becomes especially helpful when you are working on multiple branches simultaneously and need to switch between them depending on changing priorities.
Figure 3. Creating a Branch
Generally, you’ll want to create feature branches from based on the Developer Branch. This is because the Developer Branch is the staging environment in which any new features will be tested before being merged into the Main Branch, so the new feature should work with the Developer Branch. It should be set as the default branch, but if it is not, you’ll have to select it manually.
Figure 4. Using a Base Branch
After creating the Feature Branch, you’ll have to publish it to the remote before you can share it with the team. Once you do so, you can add your changes to the project and initiate a pull request, in which a maintainer of the repository will review your changes before merging it into the Developer Branch.
Figure 5. Publishing a Branch
Once you make changes, you can commit them to the Feature Branch, essentially creating a snapshot of the state of the repository that you can reference in the future, should you make unwanted changes and wish to return to a previous state. Keep in mind that committing only saves changes to your local repository. It is important that you do not commit any executable files or build artifacts, as they should be able to be built using the code in the repository. In addition, ensure that there is no private information included, such as a private SSH key.
Figure 6. Committing Changes
In order to save your changes to the remote, you’ll have to push your commits to the origin remote. By doing so, your changes are shared with the rest of the team. In addition, if you happen to lose your data on your local computer, you can still access changes you’ve pushed to the remote.
Figure 7. Pushing Changes to the Remote
Once you have merged the Developer Branch into your own branch with a merge commit, you can attempt to merge your Feature Branch into the Developer Branch.
Figure 8. Requesting a Merge into Developer Branch
Create a pull request and add any comments about the merge that the reviewer might want to know. For example, if you used a design pattern, it might help to let the reviewer know. Of course, you don’t need to leave a comment at all if you don’t think it is necessary. It is through this interface that your reviewers can interact with you.
Figure 9. Pull Request Form
Once a pull request has been initiated, reviewers or the lead developer on the team can see the changed files by selecting the “Files changed” tab. They may also comment on specific lines of code by selecting the “+” after each line number. When a pull request has been fully reviewed, the reviewer may select the “Review Changes” button and approve the request, or deny it, asking the developer to make suggested changes first.
Figure 10. Reviewing a Pull Request
Once the code has been adequately reviewed and approved by the reviewers, they may merge the Feature Branch into the base branch, which should be the Developer Branch. The method of merging is up to the repository maintainer, but assuming that the code has been rigorously tested and is in a good state, it is neater to do a “Squash and merge” so that there aren’t too many messages in the repository’s commit history.
Figure 11. Merging a Feature Branch into Developer Branch
With that, the new feature has been merged into the development branch.
Once the lead developer on the team feels the development branch is in a good state, a pull request can be initiated to merge the code from the development branch to the main branch. The administrators of the repository will work with the lead developers to address if there are any conflicts and will validate that the CI/CD pipeline checks have all passed and been approved. Once validated and triaged, the administrator will approve the merge request and allow the merge to main.
Note. From Feature branching using feature flags [Photograph], by J. Baker, 2021, (https://dzone.com/articles/feature-branching-using-feature-flags-1).