Git and CI/CD Sandbox

This repo is for practicing git best practices as well as CI/CD changes made during the of summer 2020.

Repo Setup 💻

• Clone the git-sandbox repo to your local machine git clone https://github.com/itcig/git-sandbox.git
• Once the repo has been cloned open the git-sandbox directory and run yarn to install the npm packages
• Next run cd src && composer install to install the php dependencies
• Create a Personal access token for release-it
• Then add the following to your ~/.bash_profile export GITHUB_TOKEN="[github personal access token]"

Git Worksheet ✍️

Review the Git Best Practices below.

Step One - The new process

1. Decided what feature you would like to add to the sandbox (this can be as complex or simple as you'd like)
2. Create a feature branch using the format outlined in the Branches section
3. Make some changes
4. Use git add [file name] to stage the changes
   • Commit the change(s) grouping them into commits using the standards outline in the Commits section
5. When ready to commit type git commit and press return
6. Write the commit message (title and body) utilizing the Commit Messages Section
7. Repeat the prior three steps until all changes for your branch have been committed
8. Push the changes to the remote repo git push origin [your branch name]
9. Create a Pull Request on Github from [your branch name] into the main branch
10. Use the format outline in the Pull Requests section to create a name and body for the PR's message
11. Scroll down and click Squash and merge (if this is not an option the Merge button will have a dropdown that can be clicked to select Squash and Merge)
12. Using the format listed in the Merge section create the commit message for the merge (this will be the only commit that will be seen on the main branch)
13. After the merge is completed see the commit log for the main branch, you should only see the merge commit listed
14. Create a new release for your merged changes (this will be automated later on) see the Releases section
15. View the release on Github

Step Two - Correcting commit messages

1. Again, create a branch off of the main branch for a bug or feature git checkout main then git checkout -b [my step two branch]

2. As before make some changes

3. Commit the changes, but include some typos, bad information, or incorrect fromatting in the commit message(s)

   • Make sure there are multiple commits

4. Push the changes to Github

5. Now from your branch create a new branch git checkout -b [my step three branch], this will be used in Step Three

6. Push this duplicate branch to the remote/Github git push origin [my step three branch]

7. Switch back to the branch you made in step one git checkout [my step two branch]

8. Now that we've got some incorrect commit messages we can fix them using git rebase

9. Make sure you've got the most recent changes git pull origin [your branch] (you should, but this is generally a good idea to make sure another developer hasn't added changes)

10. Now lets find the last good commit type git log to display all the commits on the branch from most recent to oldest

11. Count how many commits from the begining of the list you'd like to change

12. Press q to quit out of the git log

13. To correct the git log (essentially the branch's history) run git rebase -i HEAD~[number of commits from the begining you need to go back]

    • If you made 3 commits and all 3 need to be adjusted the command would be git rebase -i HEAD~3
    • Vim will open and you'll see a list of commits and information on how to use rebase as seen below:

    pick 3888316 chore!: Gitignore, Composer, and index Setup
    pick 4340aef feat(js): Add alert for thing
    pick 2e3ef06 feat(js): Add alert for thing (#5)
    pick 72d4605 refactor: Add empty line to EOF
    
    # Rebase 7d65997..72d4605 onto 72d4605 (4 commands)
    #
    # Commands:
    # p, pick <commit> = use commit
    # r, reword <commit> = use commit, but edit the commit message
    # e, edit <commit> = use commit, but stop for amending
    # s, squash <commit> = use commit, but meld into previous commit
    # f, fixup <commit> = like "squash", but discard this commit's log message
    # x, exec <command> = run command (the rest of the line) using shell
    # b, break = stop here (continue rebase later with 'git rebase --continue')
    # d, drop <commit> = remove commit
    # l, label <label> = label current HEAD with a name
    # t, reset <label> = reset HEAD to a label
    # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
    # .       create a merge commit using the original merge commit's
    # .       message (or the oneline, if no original merge commit was
    # .       specified). Use -c <commit> to reword the commit message.
    #
    # These lines can be re-ordered; they are executed from top to bottom.
    #
    # If you remove a line here THAT COMMIT WILL BE LOST.

14. Each commit will be prefaced with pick by default meaning the changes and message will be uneffected, you can adjust what will happen next by pressing i to enter Vim's insert mode

15. Now you can change the preface from pick to reword on the commit(s) you would like to change the message(s) on

16. Once you've updated the prefaces press the escape key to exit Vim's insert mode then type :wq to save and exit Vim

17. The rebasing will start and when it gets to the commit(s) set to reword Vim will appear, you can press i to enter Vim's insert mode and then edit the message

18. Once the messages have been adjusted press the escape key and enter :wq to save and exit Vim

    • If you get an error try running git rebase --continue to keep the rebase moving forward

19. Once the rebase is completed you will need to force push the branch to the remote, you can do this with the following command git push origin [your branch] --force

    • This WILL overwrite your previous commits, so only do this part if you're absolutly certain the local changes are correct

20. After this completes you can check Github and you should see the new commit messages

Step Three - Removing Commits

1. Checkout the duplicate branch you created in Step Two git checkout [my step three branch]
2. This time we'll remove all the commits you had previously made
3. Run the following to start the rebase git rebase -i [the number of commits to be removed]
4. Just like before each commit will be prefaced with pick to change that press i to enter Vim's insert mode
5. Now you can change the preface from pick to drop on each of the commits you had made in Step Two
6. Once you've updated the prefaces press the escape key to exit Vim's insert mode then type :wq to save and exit Vim
7. The rebasing will start, this time as no messages are being updated Vim should not open, instead once it's completed you should see a message similar to: Successfully rebased and updated refs/heads/[my step three branch].
8. You will once again need to force push the branch to the remote, you can do this with the following command git push origin [your branch] --force
9. After this completes you can check Github and you should see all the commits have been removed from the history/git log

Step Four - Removing commits from the main branch

1. Again, create a branch. This time for bug that doesn't exist
2. As before make some changes
3. Commit the changes using the new format
4. Push the changes to Github, then create a pull request once again using the new format
5. Merge the PR from your bug branch into the main branch using the squash and merge format outlined below
6. Now that we've got an incorrect PR on the main branch we can fix it using git rebase
7. Locally checkout the main branch git checkout main
8. Make sure you've got the most recent changes git pull origin main
9. Now lets find the commit we'd like to roll back to git log will display all the commits on the branch from most recent to oldest
10. Find the commit you'd like to roll back to and count how many commits came after it
    • Assuming the PR commit you made is the only commit we'd like to remove, the number of commits above the last good commit should be 1
11. Press q to quit out of the log
12. To roll back the main branch X commit(s) and leave the git log (essentially the branch's history) clean and readable run git rebase -i HEAD~[number of commits to remove]

Git Best Practices 👍

Branches

• Create new branches off of master prefacing them with your initials followed by a hyphen
• Then add the name of the feature or bug ie. hr-my-feature or hr-publication-nav-bug

Commits

• Make the smallest changes possible for each commit
• A commit should revolve around a single fix or task
• Only commit when a block of work is complete

Commit Messages

• Separate subject from body with a blank line
• Limit the subject line to around 50 characters
  • If you're having a difficult time fitting everything into 50 characters the commit may be too large
• Use the imperative mood in the subject line
  • Spoken/written as if giving a command/instruction
  • ie. Clean your room, Close the door, Take out the trash
  • If applied, this commit will [commit subject line here]

Format

[type][(optional scope)]: [description]

[optional body]

[optional footer]

Type

• feat | A new feature
  • Correlates with MINOR in semantic versioning
• fix | A bug fix
  • Correlates with PATCH in semantic versioning
• docs | Documentation only changes
• style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor | A code change that neither fixes a bug nor adds a feature
• perf | A code change that improves performance
• test | Adding missing tests or correcting existing tests
• build | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
• ci | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
• chore | Other changes that don't modify src or test files
• revert | Reverts a previous commit

Scope

• Additional contextual information contained within parenthesis
• A noun describing a section of the codebase

Description

• Short summary of the code changes

Body

• Additional contextual information about the code changes
• Separated by an empty line from the description
• Wrap the body at 72 characters
• Not all commits require a body, especially when the change is simple
• MUST be provided after BREAKING CHANGE:
• Use the body to explain what and why vs. how
  • The code explains how
  • Explain the problem that the commit solves
  • Are there side effects the commit causes?

Footer

• May be one or more lines
• Contains meta-information about the commit
  • Related pull-requests, reviewers, breaking changes, with one piece of meta-information per-line

Breaking Change:

• BREAKING CHANGE: | at the beginning of its optional body or footer section introduces a breaking API change
• Correlates with MAJOR in semantic versioning
• May be part of commits of any type
• Optionally a ! may be added following the type to draw attention to a breaking change ie. chore!: something breaking
• BREAKING CHANGE: is still required in the body or footer
• Indicated at the very beginning of the body section, or at the beginning of a line in the footer section
• All capital letters required

Pull Requests

• The message should summarize the group of commits with a brief description of the bug or feature
• The body should contain bullet points to summarize the commits within
  • This doesn't need to be 1 to 1 if you add some logic, update the docs, and update styles those could all be contained in a single bullet
  • May also exclude minor dependency updates as well

Merging

• Always choose to Squash and merge on github
• Use the same commit title structure as a standard commit see above Commit Messages section
  • The PR commit's title should have a link back to the PR itself appened to the end
  • This should happen automatically when you click Squash and merge and Github should autolink the PR if you enter #[PR number]
  • Alternativly you may append the following to the title [#<pull request number>](https://github.com/itcig/<repo>/pull/<PR number>)
  • The end result should look like this 👉 (#1)
• The body will be auto generated and should contain bullets for every commit within using the commit's title as the text following the bullet, the commit's body if it has one will be listed beneath the bullet

Releases

• A release should be created after a PR has been merged
• Determine whether the changes in the PR are considered a patch, minor, or major change see the below Semantic Versioning section or use look at the Git Commit Types listed above
• Run the corresponding command to create the release
  • For PATCH run yarn release:patch
  • For MINOR run yarn release:minor
  • For MAJOR run yarn release:major

Semantic Versioning

v0.0.0 translates to major.minor.patch

MAJOR - when the changes are incompatible with the API

• All Breaking Changes will be classified as a major change

MINOR - when the changes add functionality in a backwards compatible manner

• This will include new features

PATCH - when the changes fix a bug in a backwards compatible manner

• This will include bug fixes

Google Cloud Build