Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (59 loc) · 3.79 KB

CONTRIBUTING.md

File metadata and controls

86 lines (59 loc) · 3.79 KB

Contributing to dotfiles

Inspired by LunarVim contributing guideline.

Setting up development tools

For editing shell scripts

  1. Formatter: shfmt.
  2. Linter: shellcheck.

(Optional)

Install pre-commit which will run all linters and formatters for you as a pre-commit-hook.

Code Conventions

All shell code is formatted according to Google Shell Style Guide. Use two spaces instead of tabs.

shfmt -i 2 -ci -bn -l -d .

Pull Requests (PRs)

Branch Naming

Name your branches meaningfully.

Real world example: (feature|bugfix|hotfix)/(issue-number)-what-my-pr-does

Commit Messages

  • Commit header is limited to 50 characters - source.
  • Commit header should answer the "what" question - source.
  • Commit body and footer is limited to 72 characters per line - source.
  • Commit body should answer the "why" question - source.

Commit header format:

<type>(<scope>?): <summary>
  │       │           │
  │       │           └─> Present tense.     'add something...'(O) vs 'added something...'(X)
  │       │               Imperative mood.   'move cursor to...'(O) vs 'moves cursor to...'(X)
  │       │               Not capitalized.
  │       │               No period at the end.
  │       │
  │       └─> Commit Scope is optional, but strongly recommended.
  │           Use lower case.
  │           'plugin', 'file', or 'directory' name is suggested, but not limited.
  │
  └─> Commit Type: build|ci|docs|feat|fix|perf|refactor|test

Commit Type Guideline

  • build: changes that affect the build system or external dependencies (example scopes: npm, pip, rg)
  • ci: changes to CI configuration files and scripts (example scopes: format, lint, issue_templates)
  • docs: changes to the documentation only
  • feat: new feature for the user
  • fix: bug fix
  • perf: performance improvement
  • config: changes to configuration files
  • refactor: code change that neither fixes a bug nor adds a feature
  • test: adding missing tests or correcting existing tests
  • chore: all the rest, including version bump for plugins

Real world examples:

feat(quickfix): add 'q' binding to quit quickfix window when focused

fix(installer): add missing "HOME" variable

Commit flow

Inside a feature branch, the commits must be small and atomic (self-containing and non-broken). Feature working flow should be the following:

  1. Create WIP commits in possibly arbitrary order, but try to keep them scoped.
  2. When the feature is finished, reorder commits in a meaningful order starting from the main functionality and adding the supplementary things in separate atomic commits. The first commit must be the one with the main feature + a good description as git providers extract it to prefill {P|M}R information. If necessary, utilize fixup/squash during the interactive rebase.
  3. Utilize manual git commit --fixup (git fixup in this dotfiles) or git absorb with interactive rebase + --autosquash to be able to embed requested review changes into the semantically similar commits.

Source.