Git workflow

This document describes the git workflow that should be used when contributing to Tosca/ZA projects. It assumes a very basic understanding of git (commits, branches, etc.) using the command line.

Cloning the repository

1. Clone the repository. Click the green "Clone or download" button ①, and copy the url ② and type

   git clone clone-url

   at the terminal. Replace clone-url with the url that has been copied to your clipboard.

Making changes

Before you make any changes, you should make a branch. Remember to never commit to the main branch. The command git status will tell you what branch you are on. I recommend putting the git branch in your command prompt, so that you will always know what branch you are on. See this guide on how to do this.

It is important that you never commit to master

1. Update master. Before you make any changes, first checkout master

   git checkout master
   

   and pull in the latest changes

   git pull
   

   This will make it so that your changes are against the very latest master, which will reduce the likelihood of merge conflicts due to your changes conflicting with changes made by someone else.

2. Create a branch. Once you have done this, create a new branch. You should make a branch name that is short, descriptive, and unique. Some examples of good branch names are fix-install, docs-cleanup, and add-travis-ci. Some examples of bad branch names are feature, fix, and patch. The branch name choice is not too important, so don't stress over it, but it is what people will use to reference your changes if they want to pull them down on their own computers to test them, so a good name will make it easier for others to understand what your branch does. In this example, the branch name is fix-install.

   To create the branch, run

   git checkout -b branch-name

   (replace branch-name with the branch name you chose). This will create a new branch and check it out. You can verify this with git status.

3. Make your changes and commit them. Once you have created your branch, make your changes and commit them. Remember to keep your commits atomic, that is, each commit should represent a single unit of change. Also, remember to write helpful commit messages, so that someone can understand what the commit does just from reading the message without having to read the diff.

   For example, at the command line, this might look like

   git add filename [filename ...]
   git commit
   

   This will open an editor where you can write your commit message.

4. Push up your changes. Push your changes to your fork. Do this by running

   git push branch-name

5. Make rebase from base branch

   
   git rebase branch_name main
   

   Assume the following history exists and the current branch is "fix":

   
        C--D--E      fix
       /
   A--B--F--G        main
    

From this point, the result of either of the following commands:

   git rebase main fix 
   git rebase main (when already on the fix branch)
   

would be:

              K--L--M      fix
             /
   A--B--F--G               main
   

7. Make a pull request.

8. Make rebase from base branch

   
   git rebase main branch_name
   

9. Merge the feature branch in the base branch Assume the following history exists and the current branch is "main":

      C--D--E      fix
    /               
A--B--F--G--k      main

Then

git merge fix   

will replay the changes made on the fix branch since it diverged from main (i.e., B) until its current commit (E) on top of main, and record the result in a new commit

      C--D--E      fix
    /        \        
A--B--F--G--k--L   main