Using Git

This page explains different Git features that documentation writers must be aware of if they want to contribute to the official website → HPC

Create Your Local/Feature branch

  • Create a new branch where you want to do the work and contribute.

Syntax :

git checkout -b <branch-name> master

Naming Convention

  • If there is a new feature to be added to the website, follow the below syntax:

Syntax:

git checkout -b feature/<task-name> master

Example:

git checkout -b feature/mpi-docs master

  • If you have any updates, fix to the existing feature/task in the website, you can follow the below syntax:

Update/Fix

Syntax

Update

git checkout -b update/<feature-name> master

Fix

git checkout -b fix/<feature-name> master

The branch name has to be descriptive and meaningful.

Add and Commit Your Changes

After the local branch is created, you can edit the files and do your work. Once all the work is done, the next step is to commit your changes.

First, you need to add/prepare the changes staged for the next commit. To do that, run the git add command.

Example 1

git add newfile.txt

It adds the file newfile.txt to the staging area.

Example 2

git add .

It adds/stages all the files in the working directory.

Once all the changes are staged, use the Git commit command to commit your changes.

Syntax:

git commit -m <commit-msg>

Push the Changes

Before pushing changes to GitLab, it’s important to understand the GitLab development workflow. To learn more about the workflow, refer to the page → GitLab Development WorkFlow

In order for the above link to work, make sure you are connected to the HPC Team VPN.

To push the committed changes to the remote branch,

Syntax:

git push origin <local-branch-name>

Create Merge Request

Once all the changes are pushed to the remote branch, create a merge request to merge it to the master branch. Add a reviewer(write access to the repository) to the merge request to approve your pushed changes. Also, in the description section, describe the goal of the changes in clear manner.

CI/CD Pipeline

  • After the merge request is created to merge the changes to the master branch, the CI/CD pipeline kicks off.

  • First, it runs the build job to check for any build errors. If the build is successful, the next test job gets launched automatically.

  • The test job will run Vale which is a linting tool to check for any grammar/spelling mistakes for the changed/ newly created .adoc files which are part of the merge request. If there are any errors, the job will fail and you need to fix, commit, and push again, which triggers the pipeline again starting from the build job. However, if there are only warnings and suggestions, the job gets passed. For more information about Vale, refer to → Vale

  • After both the jobs in the pipeline is successful, it can now be merged to the master branch by the code reviewer who has maintainer access for the project repository.

  • Once the merge option is selected and confirmed by the reviewer, a new pipeline gets triggered and runs the build job again to test for any build errors before merging the changes to the master branch. If the build job is successful, a new job called deploy_dev will get launched. If the deploy_dev job is successful, it will deploy the changes to the development environment → HPC Development Environment.

  • Now, to deploy the changes to the production environment/live website → HPC Live Website, it needs to be done manually. For more information about production deployment and CI/CD pipeline, refer to →CI/CD

Other Useful Commands

Command

Purpose

git status

Working tree status of your current directory

git branch

Current branch

git diff

Shows changes between commits, commit and working tree, etc

git reset

It unstages all the changes

Git Rebasing

Git Rebasing is a useful option which is used to integrate changes from one branch to another. Thus, it can also be used to make the local feature branch that you are currently working on is in sync/up-to-date with the remote master branch.

Follow the below steps to rebase your local branch against the remote master.

  1. Check out your local feature branch. Then, run the git fetch command.

    git fetch

  2. The next step is running the rebase command. The following command rebases the current branch from remote master branch.

    git rebase origin/master

  3. Now, you might face merge conflicts. To resolve it, please refer to this useful article point_right Solving Merge Conflicts while Rebasing.

References

For more information about the Git commands, refer to the site → https://git-scm.com/docs