Skip to content

Latest commit

 

History

History
291 lines (216 loc) · 11.2 KB

source_control_and_workflow.md

File metadata and controls

291 lines (216 loc) · 11.2 KB
Raw

Source Version Control and Workflow

Table of Content

Source Version Control

This project uses git and GitHub for version control.

Some useful git aliases are shown here.

GitHub-specific commands such as cloning a repo, can be executed from command line using hub.

Both Git and GitHub provide a lot of surface for workflow automation. See available Git hooks and GitHub webhooks.

Workflow

Project's setup and automation considers the following workflow:

Master ⟶ Issue ⟶ Branch ⟶ Commit ⟶ Pull request ⟶ Merge to dev ⟶ Merge to master on release

In other words:

We have our main branch. Upon recognizing a new issue that should be worked on, we create a new branch where we carry out the changes and commit them. When done, we create a pull request to merge the changes into the main branch.

Releasing is done through tagged commits.

Workflow: Issues

This project does not apply any conventions or workflows to issues tracking and management.

Workflow: Branches

This project does not apply any conventions or workflows to branches. General advice apply:

  • Use separete master and dev branches, optionally staging branch.
  • Never modify the master directly, always make a branch from dev and merge that to dev.
  • Tag releases
  • It might be a good idea to set a convention for branch naming to include the change type or branch owner, but this is up to your needs.
  • In terms of project management, ensure that each branch has an owner.

Workflow: Commits

Commit Hooks

Hooks that run on different git actions are handled in husky property in package.json.

A lot can be going on the pre-commit hook, so before the code is actually commited. The actions are handled by lint-staged, and all the steps included can be found in .lintstagedrc.

Generally, what we want to do is to:

  1. Lint and format the code.
  2. Test the code to confirm we're not breaking anything we shouldn't.
  3. Check that we are not commiting any sensitive information.
    • Note that the NPM package that provides this detect-secrets, requires running Docker
  4. If the code has been modified during this process in any way (e.g. by formatters), add the new changes to the commit.

Conventional Commits

Why should be care about the standardized commits? Let's pose counter-questions:

Would it not be nice if the changes could be easily searched and skimmed? Or if things like versioningm releases and changelogs could be automated? And as always, reducing mental burden is imporant.

That's why the projects follows the Conventional Commits spec.

By default, the project uses commit types recognized by standard-version. If you need to modify the commit types, modify the types in .releaserc.yml as outlined in this article.

Conventional Commits: Client-side

Conventional commits are guarded when you make a commit in your workspace by a combination of Husky (git hooks), Commitlint (validation) and Commitzen (formatter). This ensures that anything you push should be conformant.

To make a commit, make sure your changes are ready and run only git commit. Commitzen will automatically ask you for commit type, message, body and other required info if necessary.

See this and this article for implementation details.

More on Commitzen here.

Conventional Commits: Service-side

Client-side checks can be bypassed either explicitly, or if the commit is made in a different environemnt or from an app/service. To make these exceptions visible on pull requests, we additionally use Zappr's option to validate commit messages.

Zappr checks for 2 things:

  • that the commit message have the conventional format.
  • that the commit message contains the reference to the issue it relates to, or an explicit no-issue.

More on setting up Zappr can be found here.

Pull Requests

Pull requests are the gates before letting a change to enter the codebase. Because of that a lot of checks happen here.

Approvals

All pull requests should be approved as a sign of acknowledgment. Zappr helps us to be explicit about the approval requirements by allowing us to write the Approval as a Code (aka AaaC, and I might have just made that up).

You can see the number of required approvals and from which groups of people they should be from in .zappr.yaml. Downside of using Zappr, however, is that it doesn't support the native GitHub's approval. Instead, Zappr's approval work by reading the comments under the PR and matching them against regexes, such as +1 or LGTM. Nevertheless, having a system which allows us to be explicit about the requirements is good for transparency.

Formatting

Zappr's specification config section allows us to validate the format of the PR.

The Zappr's Pull Request Tasks checks if all checkboxes in the PR were fulfilled.

NOTE: Pull Request Tasks would have been useful if Zappr allowed to ignore some checkboxes. Currently it required ALL checkboxes to be ticked, which is good if checkboxes represent tasks, but not good if checkboxes represent choices.

While these are minor things, it can help to catch incomplete PRs if they were to arise, which could otherwise raise issues in the future when searching for things retrospectively.

Unfortunately, Zappr's documentation is lacking in this aspect, so it might not work as expected. Nevertheless, the current settings at least require to link the PRs to their issues.

Code quality

To minimize errors and ambiguity entering the codebase, a suite of apps carry out checks like tests, code complexity and vunelrability checks, conformation to conventions, etc. See the list of GitHub apps used on pull requests used in this project.

Workflow: Other

Additional improvements to this setup could be in terms of standardized issue tracking and categorization, or project management frameworks to specify the issues and their scope.

GitHub: Integrations

  • Codecov - Checks whether the codebase fulfills specified code coverage. Expected code coverage thresholds are specified in jest.config.js.
  • LGTM - Security and code quality analysis. Can detect some security issues and code quality issues. Complements both Snyk and CodeClimate.
  • Snyk - Security analysis. Checks dependency vulnerabilities.
  • CodeClimate - Code quality review. Checks things like logic complexity, argument counts, refactoring opportunities, etc. The config can be modified in .codeclimate.yml.
  • Zappr - Pull request, commit, and approval policies as a code. Checks that commits and PRs are conformant, and that PRs receive enough approvals before accepting. The config can be modified in .zappr.yml.
  • DependaBot - Dependency management - Creates a pull request when there's a dependency that should be updated. The config can be modified in dependabot/config.yml.
  • Travis - CI pipeline. Used for testing, deploying and releases. The config can be modified in .travis.yml.
  • AllContributors - Contributors list management.

For more ways how the GitHub workflow could be automated, see ProBot (some examples in these links here)

GitHub: Web Extensions

To make it easier to work with GitHub, below is a set of web extensions that help with readability or productivity.

The full list of curated extensions can be found @ Awesome GitHub.

General

Readability/Formatting

Collaboration

Project analysis

Miscellaneous

References

Table of contents generated with markdown-toc.