Skip to content

Git Workflow

lolagarden edited this page Oct 13, 2020 · 1 revision

Git Workflow Step By Step Conventions:

  1. Fork the main repository (jabref) and make a local clone by doing the following:

    # 1. Clone your fork of the repo into the current directory
    git clone https://github.com/<github-username>/jabref
    
    # 2. Navigate to the your cloned directory
    cd <repo-name>
    
    # 3. Assign the original repo to remote (name it "upstream")
    git remote add upstream https://github.com/SE761Team4/jabref
    
    # 4. Check that you've correctly assigned 'upstream'
    git remote -v  
  2. Update your local repository master with the most recent code from the main repository.

    git checkout master
    git pull --rebase upstream master
  3. For every new issue, branch off from master and create a new branch. The branch should follow the branch naming coventions as listed on the wiki. Branch of master with the following command:

    # For example: 
    git checkout -b feature/{feature-desc}
    ...
  4. Make changes to the feature branch on the local clone, and commit when needed and with well descriptive messages - refer to Commit Messages below

  5. Test your changes by running all the tests

  6. Rebase the upstream branch into your local branch by doing the following:

    git checkout master
    git pull --rebase upstream master 
    git checkout {name-of-work-branch}
    git rebase master
  7. Push your local branch up to your forked repository by doing the following:

    git push origin feature/{feature-desc}
  8. Create the Pull Request -

    • On the "Pull Requests" tab of the main repository, open a pr from youruser:feature/example-branch => SE761Team4:master
    • The pull request should have a title that summarizes the changes.
    • The body should provide more details about what changes have been made and should reference the number of the associated issue, eg "Fixed synchronization issue. closes #123".
    • The title of the pull request should not just reference the issue number. It should succinctly describe the actual changes.
    • Refer to the Pull Request template
    • Two other group members must review and approve of the pull request.
    • Once the reviewer approves the pull request, they can merge your contribution into the main repository. Do not merge your own pull requests.

Pull Request Conventions

Aside from the "Create a Pull Request" instruction above, simply... do not merge your own pull requests.

Branch Naming Conventions

Aside from branch prefixes (e.g. username/feature/...), please name the branches hyphen separated (-) and all lowercase

Branch Prefixes

  • Start all prefixes with your username
  • master - (Development branch) Usually integration branch for feature work and often defaults branch. For pull request workflows, the branch where new feature branches are targeted
  • feature/ - (Feature branch) Used for specific feature work or improvements. Generally branches from, and merges back into, the development branch
  • bugfix/ - (Bugfix branch) Typically used to fix development branch

Note: Typically use prefix branch feature/ when naming your branches, unless bug fixing.

Merging Branches

  • We squash feature/ and bugfix/ branches onto development master development branch
    • This way we get 1 commit per pull request
    • When you squash commits, take the time to clean up your commit messages

Further reading: Here

Commit Messages

  • Make the commit messages concise, with no period at the end.
  • The main purpose of commit messages is to make it easy to navigate between commits.
  • Reference the issue tracker at the end (i.e. "This handles/relies on issue #12")
  • If the issue you are referring to is fixed, write at the end of the git commit message This handles issue #24.
  • If the issue relies on an issue to be fixed, write at the end of the git commit message This relies on issue #25.

Further reading: Here

Additional Resources:

ohmyz - Make terminal pretty

sourcetree - UI for git

dev.to - common Git commands to get started