Git Workflow

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