Git and Github guide#
This guide is to help new contributors setup git, github and navigate their way through making contributions to moja global repositories. It covers the entire process of contributing right from installing git to opening pull requests.
Setup this project using Git#
Before setting up this project using Git make sure you have installed and configured git by following the instructions here.
Fork and Clone this project#
In your browser, visit https://github.com/moja-global/FLINT.Cloud. In the upper left corner, there is a Fork button. Please click on it to create a fork/copy of the repository on your profile.
In the terminal screen, clone this repo by running the command where
your-usernamerepresents your Github username.
git clone https://github.com/<your-username>/FLINT.Cloud/
Enter into the newly created project folder by running the command
Configure upstream for the fork so that git can sync work from the upstream if it is updated by running the command
git remote add upstream https://github.com/moja-global/FLINT.Cloud/
Check if upstream is configured by running the command and check if upstream is shown or not.
git remote -v
Claim an issue#
This section will demonstrate how to claim an issue to work on using botmojaglobal.
To work on an issue, claim it by adding a comment with
@botmojaglobal claim to the issue thread. botmojaglobal is a GitHub workflow bot forked from the zulipbot; it will assign you to the issue and label the issue as
in progress. Some additional notes:
You can only claim issues with the
Good for newcomersor
Help Wantedlabels. botmojaglobal will give you an error if you try to claim an issue without one of those labels.
Please feel free to ask questions on how to approach the issue or if the tests are failing. The maintainers/reviewers will try to get back to you as soon as possible. You can reach us on the moja-global slack, or through Github.
If your pull request has some requested changes, after working on it don’t forget to leave a comment asking for a review since the reviewers aren’t notified when a pull request is updated.
Make a contribution#
This section will show you step-by-step how to make a contribution to FLINT.Cloud using git.
FLINT.Cloud stable branch is master. All pull requests should be against master branch only. Make sure you are in the project directory and checkout to master branch with this command.
git checkout master
Choose an issue to work on. We have issues specifically labelled
Good for newcomersand
Help Wantedfor new contributors to claim. Before starting to work on any issue, make sure you have claimed it.
Create a new feature branch from master branch to work on. The feature branch should have a short name that is relevant to the issue that you will be working on. For example, if you are working on improving documentation in the readme for adding a badge, the branch can be name
git checkout -b <feature-branch-name>
Work on the task. Add tests and documentation for your changes if required. When you are done with your changes, you can check all the files changes using the following command.
Add the relevant files and commit the changes. Please make sure that only those files required for this contribution are added. You can later modify your pull request to add other files as per your requirement.
git add <file> <file> ...
While committing the changes, make sure your commit message follows our commit-message guidelines mentioned here.
git commit -m "relevant commit message"
Make sure your fork is in sync with the latest changes of master. For this rebase your branch against the latest master by following the commands below.
git checkout master git pull origin master git checkout <your-branch-name> git rebase master
Incase there are any merge conflicts on running the rebase command, follow this guide to resolve them.
You can now push your changes onto your feature branch using the command below.
git push origin <your-branch-name>
Create a pull request for your contribution#
You can now create a pull request to get your changes merged into the upstream master branch. Follow this step-by-step guide to create a pull request on Github.
Navigate to the pull requests tab under FLINT.Cloud. Click on the New pull request button. Compare your feature branch against the master branch to create the pull request. Fill the pull request template by linking the issue number solved.
Incase your pull request is a work in progress, don’t forget to add “WIP” in the title of your pull request to let the maintainers know that the pull request is not ready for review yet.
Please be patient, someone from our team will review your pull request shortly and provide feedback. Incase there are changes requested, you can follow the section below on how to update/modify your pull request.
Also make sure that your pull request is in sync with the latest master at all times.
NOTE: Don’t forget to get credits for your contributions once it gets merged by following this guide here.
Modify your pull request#
Incase your pull request needs further changes, you can update your pull request by following the steps below.
Checkout on your feature branch of the pull request.
Add the changes as required and commit using the amend flag. This will update the last commit thus keeping the commit history clean and within a single commit.
git add <file1> <file2> git commit -amend
Push this onto your feature branch but this time with force flag. This will update the pull request automatically. The reviewer won’t be notified about this updation, so leave a comment in your pull request if you want a review.
git push origin <your-branch-name> --force
Hadolint is a Dockerfile linter that helps you build best practice Docker images.