Development Workflow with Git and Github - TeamCrown/First-project GitHub Wiki

TeamCrown Development Workflow with Git and Github

Git provides a tremendous amount of freedom and little guidance, so teams often have to define their own best practices. This document defines the workflow we use in TeamCrown projects.

We highly recommend using Git CLI, since it is consistent across platforms.

If you think more than one person is needed to work on a single branch, consider breaking the work into smaller units.

Setup

  1. Install Git

  2. Set your username and email for Git:

    • git config --global user.name "Your name here"
    • git config --global user.email "[email protected]"

  3. Follow the instructions here for generating a new SSH key and adding it to the ssh-agent. Do not forget to add your SSH key to your GitHub account.

  4. Check if your setup is complete:

    You should see a message like Hi YOUR_USERNAME! You've successfully authenticated...

  5. Clone the repository:

    • git clone https://github.com/TeamCrown/First-project.git

    Do NOT create your own fork. It is not the workflow we will use.

  6. Enter to the project folder:

    • cd First-project

  7. Check if everything is setup correctly:

    • git remote --verbose

    The output should look like

    origin https://github.com/TeamCrown/First-project.git (fetch) origin https://github.com/TeamCrown/First-project.git (push)

The Workflow

The code changes you commit should tie back to a task on Trello. If that is not the case, please create a task.

master represents the official history and should ALWAYS be deployable. For each feature, a developer creates a new branch. For clarity, make sure to add your name as prefix and use descriptive names like minasie.github-workflow for your branches.

To create a branch:

  1. Checkout to master:
    • git checkout master
  2. Pull latest changes:
    • git pull
  3. Create a new branch and switch to it:
    • git checkout -b your-name.new-feature-branch

Branch management

While working on a new feature branch, it is a good idea to commit often. This allows us to move forward without fear since if something goes wrong you can revert back easily without losing too much work. Keep in mind that it's better to divide the work into small chunks so that each commit is easily digestible by every developer.

Commit your code

  1. Get the status:

    • git status

    This command will give you a list of all the updated, added and deleted files.

  2. Files can be added individually or all at once:

    • git add FILE or git add -A

  3. Now we are ready to create a commit with changes:

    • git commit

This will open selected text editor two write a commit message.

If the change is not complicated:

* `[CHANGE_TYPE] + one line commit message`

If the change is complicated:

* `[CHANGE_TYPE] + one line commit message + an empty line + detailed explanation lines`

A good commit message would look like:

* `[doc] Add Github workflow`

As seen above, we prefer to use an imperative form for simplicity. The change type is in brackets. Some other examples of change type could be your team's name or specific technology like [mobile], [backend], [web], [db] etc.

Please be consistent and follow the conventions.

Rebase and (squash if needed) your branch

Squashing will condense commits into a new commit. This is important to keep the commit history clean.

  1. git rebase -i master

This will open your default editor and present you the list of commits to be rebased. Each commit in your branch is listed at the top of the file. You should keep the top/oldest commit and squash all of the other commits into it. To do this, simply change pick to squash for all the commits except the top one.

As rebase processes your commits, it may run into a merge conflict (for example, if you and upstream changed the same part of a file). If this happens, rebase will pause and wait for you to manually resolve the conflict. To do this, simply run git status to find out which file(s) have conflicts and then go into each one and resolve them.

  1. Once you’re done, first run

    • git add -A This will stage each file.

  2. Continue the rebase with:

    • git rebase --continue

  3. To push the new feature branch to the remote repo, simply do the following:

    • git push -u origin your-name.new-feature-branch

At this point, you are ready to create a Pull Request for the new feature.

Create a Pull Request

  1. Click on New pull request on the project site.
  2. Select master as the base branch.
  3. Select your-name.new-feature-branch as the compare branch.
  4. Add one or two reviewers.

The reviewers should review the PR in 24 hours and leave their comments. Note that we do not allow any direct pushes to masters without creating a PR and getting approval from reviewers. Once you addressed all the comments on your PR, and rebase your fix comments with the rebase workflow above, it's time to push your changes.

  1. Rebase on master again to be up-to-date:

    • git rebase -i master

    This time you might not have to squash anything.

  2. Push on your feature branch so that your PR will get closed automatically. You might have to force-push, in that case, use the -f flag.

    • git push or git push -f

  3. Checkout to master:

    • git checkout master

  4. Retrieve the changes from your feature branch to master:

    • git rebase your-name.new-feature-branch

  5. Push to remote master:

    • git push

Congratulations! You are ready to contribute TeamCrown!