Our GitFlow Process (Reference)

[GillianTrethewey]

Our Version Control Process (including Branch and Commit Naming)

User Story Description

As a team, we want to follow clear instructions for using Git, so that our GitFlow process is bug-free.

Steps to Follow

1. We will be working on the develop branch rather than the main branch. I have made develop the default branch so that it is less likely that mistakes are made.

2. From the develop branch ON GITHUB, you are going to make a branch under develop. For our process, do NOT do this on your local machine. You can do this with the dropdown or the branches tab.

Important: You need to name the branch using best practices. More information is at the bottom of these Steps.

<category/reference/initials-description-in-kebab-case>

feature/issue-XX/initals-amend-readme-github-team-practice

3. Using your Terminal, navigate to your local folder on your computer where you're working on the project. Clone the files onto your local machine if it's the first time, or pull your files for subsequent times. Ideally you should be using the SSH method to clone. The cloning methods are found by clicking the green CODE button in GitHub.

   git clone git@github.com:chingu-voyages/v44-tier2-team-26.git

4. cd into your folder and check your files and branches:

   git branch -a

5. Now go onto the develop branch (if it's the default branch you'll already be on it, signified by the asterisk):

   git checkout develop

6. Create and move onto a new branch locally with the same name as what you created in step 2:

   git checkout -b feature/issue-XX/initals-amend-readme-github-team-practice

7. You can check you're in the right place:

   git branch -a

8. Write code or make changes and edits. You can add and commit SEVERAL TIMES during this process which tracks your work and helps you revert if you want to an earlier version. Commit early and often. Push once.

   git add -A

   Essential to capture all changes to all branches and is good practice. There are other methods but using -A is preferred.

git commit -m '<category: do something; do some other things>'
EXAMPLE:
git commit -m "feat: added text to the readme file"

9. The moment you've been waiting for ... one push to rule them all:

   git push

10. Open a Pull Request upon prompt on the GitHub remote repo.

11. Wait for 2 reviews to happen, and address any suggestions you might receive for improvement. Once you are fully approved, you will merge into develop. Watch the branches are correct on the menu.

12. I have allowed force pushes, but please don't do this. This is more for convenience after the Voyage is done if, for example, a final image is needed for the Readme file.

13. It's simpler to clear your local repo by deleting the files and pulling down fresh, but this command might work as well:

    git fetch --prune origin

Additional Considerations The main branch will be pushed to from development on average once a week to create our MVP (Minimum Viable Product). We will make our MVP as soon as possible. It won't look pretty at first, but it will work.

More Information on Naming Branches and Commits

Reference: https://dev.to/varbsan/a-simplified-convention-for-naming-branches-and-commits-in-git-il4

Branch Naming Convention

Category

A git branch should start with a category. Pick one of these: feature, bugfix, hotfix, or test.

• feature is for adding, refactoring or removing a feature
• bugfix is for fixing a bug
• hotfix is for changing code with a temporary solution and/or without following the usual process (usually because of an emergency)
• test is for experimenting outside of an issue/ticket
• (setup can be used for initial file structures)

Reference

After the category, there should be a "/" followed by the reference of the issue/ticket you are working on. If there's no reference, just add no-ref.

Description

After the reference, there should be another "/" followed by a description which sums up the purpose of this specific branch. This description should be short and "kebab-cased".

By default, you can use the title of the issue/ticket you are working on. Just replace any special character by "-".

To sum up, follow this pattern when branching:

git branch <category/reference/description-in-kebab-case>
or
git branch <category/no-ref/description-in-kebab-case>

Examples:

You need to add, refactor or remove a feature:

git branch feature/issue-42/create-new-button-component

You need to fix a bug:

git branch bugfix/issue-342/button-overlap-form-on-mobile

You need to fix a bug really fast (possibly with a temporary solution):

git branch hotfix/no-ref/registration-form-not-working

You need to experiment outside of an issue/ticket:

git branch test/no-ref/refactor-components-with-atomic-design

Commit Naming Convention

Category

A commit message should start with a category of change. You can pretty much use the following 4 categories for everything: feat, fix, refactor, and chore.

• feat is for adding a new feature
• fix is for fixing a bug
• refactor is for changing code for peformance or convenience purpose (e.g. readibility)
• chore is for everything else (writing documentation, formatting, adding tests, cleaning useless code etc.) After the category, there should be a ":" announcing the commit description.

Statement(s)

After the colon, the commit description should consist in short statements describing the changes.

Each statement should start with a verb conjugated in an imperative way. Statements should be separated from themselves with a ";".

To sum up, follow this pattern when committing:

git commit -m '<category: do something; do some other things>'

Examples:

git commit -m 'feat: add new button component; add new button components to templates'
git commit -m 'fix: add the stop directive to button component to prevent propagation'
git commit -m 'refactor: rewrite button component in TypeScript'
git commit -m 'chore: write button documentation'

[GillianTrethewey]

We will all go through these steps to modify the README.md file. Please comment when you are done and I will close out the Issue once all 4 of us have practiced. Have fun and code on!