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-username represents your Github username.

git clone https://github.com/<your-username>/FLINT.Cloud/

Enter into the newly created project folder by running the command

cd FLINT.Cloud

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

Now, the project is setup using Git. Please carry on with instructions on how to set this up on Windows or Linux here. You can revisit this section when you are ready to make a contribution.

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 newcomers or Help Wanted labels. 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 newcomers and Help Wanted for 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 add_badge_readme.

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.

git status

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

About Hadolint#

Hadolint is a Dockerfile linter that helps you build best practice Docker images.