Project Management¶
An Overview¶
We utilize git
and GitHub extensively for version control and project management. This is crucial since we must
keep track of hundreds of bugs, improvements, and changes for several
repositories.
We use GitHub tools to track and implement changes to the software. First, we
use GitHub issues to identify and track bugs/issues/features, and
GitHub pull requests or “PR” so that a developer can suggest a set of
changes to be merged into the main
/master
branch. Within these
issue and PR tracking, we use labels to indicate what these changes/problems
pertain to. Each repository has a set of labels. Labels are helpful to
understand scope and impact and aids in GitHub search engine optimization.
To understand the scope of any work, we use GitHub milestone tracking.
Finally, we use GitHub project boards to illustrate and manage issues and
PRs. Each repository has its own project board. These are kanban style boards
with several columns/lists.
DevOps workflow¶
The general workflow are as follow when starting any improvement:
Create a new GitHub issue if one does not exist. Begin tracking it in the project board
Create a new branch locally
Commit changes to branch and push them to the new branch on the remote repository (i.e. GitHub)
Create a PR within the repository to merge the new branch into the
main
/master
branchA team member reviews the PR (if enough developers are on staff). Self-review are OK if staff is limited.
The changes are merged into the
main
/master
branch and any associated tags are pushed to the remote repositoryThe software is manually deployed
Note: The default branch name is set to “main” starting Oct 1, 2020, not “master” anymore. For more info: please see Github rename master to main . Certain repositories still have default branch as “master”.
Branching¶
It is strongly recommended to use git
branches for software development.
This is because, at any point, multiple features/bugs are being addressed,
and changes pushed directly to the main branch could break the software if
it is untested or has not been reviewed. Branching is a common Developer
+ Operations (“DevOps”) best practice. To create a new git
branch, use
the following git
commands: ( -b
is to create a new branch)
$ git pull origin main
$ git checkout -b <new-branch>
To checkout an existing branch:
$ git branch # To see existing branches
$ git checkout <branchname>
In terms of branch names, it is strongly recommended to name branches so it is clear and concise. We strongly recommend including:
The GitHub issue number
Whether it is a feature/enhancement or a bug fix
A short description
The above ensures an easier understanding to the software development team. Examples include:
feature/235_preserve_prep
for LD-Cool-P#235hotfix/229_400_error
for LD-Cool-P#229chore/242_gitignore
for LD-Cool-P#242
Note: Our branching model initially followed a git-flow
workflow with
features, hotfixes, and releases; however, we later moved away from that
model and now use a GitHub flow workflow where all changes are merged into
the main
/master
branch after review and testing.
Pushing to a remote branch¶
After updating files, we can push the changes to remote branch. It is important to push to a branch (not main
) so that a team member can review the changes over a pull request.
use the following git
commands:
$ git add .
$ git commit -m "<message>"
$ git branch # list all the branches and * is the current branch
$ git push origin <branchname> # push to a remote branch
In accordance with git’s best practices, the commit message should be short but descriptive. Avoid general messages like “updated file.txt” when possible.
Versioning and tagging¶
Before creating a new tag, we need to make sure all related files updated to reflect the new tag. These files shall be checked and updated if existing:
Update __init__.py __version__ number or related configuration
Update setup.py variables such as version.
Review README.md and update related sentences.
Update CHANGELOG.md by adding changelog message
In all of our software, we conduct version tagging. Here, each new version refers to a change to the codebase that is to be deployed. We loosely follow Semantic versioning (SemVer), which denotes changes as MAJOR (X), MINOR (Y), and PATCH (Z). There are two differences with our method of versioning against SemVer:
We use the patch denotation for both hotfixes and small enhancements to software.
We use MINOR denotation for large/larger enhancements (e.g. a completely new feature rather than an improvement to an existing feature).
MAJOR remains the same, for incompatible API changes. We try to avoid the latter as much as possible.
While some open-source software teams may not use version tagging, there are
many advantages. First, this step ensures that we have continuous delivery
of our software. Second, for some of our software, we automatically deploy
them on PyPI, a python
package manager that allows for easy
installation of the software. Finally, our logging tools records version
information for each software, so this allows the team to trace an issue
back to a specific PR. To tag a specific commit:
$ git tag vX.Y.Z -m "message"
$ git tag
Note: X is the MAJOR version, Y is the MINOR version, Z is the PATCH version
You will then push one tag via:
$ git push origin <tag_name>
Note: It is NOT recommended to use “$git push –tags” because the command push all tags. It is common for developers to have old or “bad” tags in their local repositories. So it’s advised to only explicitly push a tag using the above command.
Merging code¶
Direct merges to main/master branches are to be avoided. When working collaboratively, all changes must be made to a branch and a pull request opened. The pull request must be reviewed and approved by another team member before being merged to the main/master branch.
Milestone tracking¶
More details needed here.