Skip to content

Personal Style Guides⚓︎

Git⚓︎

We use Commitizen to manage both an auto-generated Changelog and incrementing the release version following semver. For both of these automated outputs to work well, please follow the Conventional Commits style, which is described in more detail below.

Commitizen Types and Scopes⚓︎

type(scope): description

  • Types
    • fix: A bug fix
    • feat: A new feature
    • docs: Documentation-only changes (code comments, separate docs)
    • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons)
    • perf: A code change that improves performance
    • refactor: A change to production code that is not a fix, feat, or perf
    • test: Adding missing or correcting existing tests
    • build: Changes that affect the build system or external dependencies
    • ci: Changes to our CI configuration files and scripts
    • A ! can be used to indicate a breaking change (refactor!: drop support for Node 6)
    • SemVer Rules
      • Based on commit type, the version will be auto-incremented: fix : PATCH // feat : MINOR // BREAKING CHANGE : MAJOR
  • Scopes
    • A Class, File name, Issue Number, other appropriate noun. As examples: build(poetry): bump requests to v3 or style(#32): add missing type annotations
  • Tips
    • What if a commit fits multiple types?
      • Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is the focus on more organized and intentional changes
    • Use git rebase -i to fix commit names prior to merging if incorrect types/scopes are used

Git Description Guidelines⚓︎

Issue Labels and Milestones⚓︎

Personal Guide

  • For Issue Labels, see [labels.yml][labels]
  • Milestones
    • Current Tasks: main milestone (name could change based on a specific project, sprint, or month)
    • Next Tasks
    • Blue Sky
Research
  • [Sane GitHub Labels](https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63) and see [sensible-github-labels](https://github.com/Relequestual/sensible-github-labels) for full descriptions of each
    • “it is much more helpful to see the status and type of all issues at a glance.”
    • One of each:
      • Status: …
        • Abandoned, Accepted, Available, Blocked, Completed, In Progress, On Hold, Pending, Review Needed, Revision Needed
      • Type: …
        • Bug, Maintenance, Question, Enhancement
      • Priority: …
        • Critical, High, Medium, Low
  • [Britecharts](https://britecharts.github.io/britecharts/github-labels.html)
    • Status: …
      • On Review – Request that we are pondering if including or not
      • Needs Reproducing – For bugs that need to be reproduced in order to get fixed
      • Needs Design – Feature that needs a design
      • Ready to Go – Issue that has been defined and is ready to get started with
      • In Progress – Issue that is being worked on right now.
      • Completed – Finished feature or fix
    • Type: …
      • Bug – An unexpected problem or unintended behavior
      • Feature – A new feature request
      • Maintenance – A regular maintenance chore or task, including refactors, build system, CI, performance improvements
      • Documentation – A documentation improvement task
      • Question – An issue or PR that needs more information or a user question
    • Not Included
      • Priority: They would add complexity and overhead due to the discussions, but could help with the roadmap
      • Technology Labels: It can create too much overhead, as properly tag with technologies all the issues could be time consuming
  • [Ian Bicking Blog](https://www.ianbicking.org/blog/2014/03/use-github-issues-to-organize-a-project.html)
    • Milestone Overview
      • What are we doing right now?
      • What aren’t we doing right now?
        • 2a. Stuff we’ll probably do soon
        • 2b. Stuff we probably won’t do soon
      • What aren’t we sure about?
    • Milestone Descriptions
      • Stuff we are doing right now: this is the “main” milestone. We give it a name (like Alpha 2 or Strawberry Rhubarb Pie) and we write down what we are trying to accomplish with the milestone. We create a new milestone when we are ready for the next iteration.
      • Stuff we’ll probably do soon: this is a standing “**Next Tasks**” milestone. We never change or rename this milestone.
        • We use a permanent “Next Tasks” milestone (as opposed to renaming it to “Alpha 3” or actual-next-iteration milestone) because we don’t want to presume or default to including something in the real next iteration. When we’re ready to start planning the next iteration we’ll create a new milestone, and only deliberately move things into that milestone.
      • Stuff we probably won’t do soon: this is a standing “**Blue Sky**” milestone. We refer to these tickets and sometimes look through them, but they are easy to ignore, somewhat intentionally ignored.
      • What aren’t we sure about?: issues with no milestone.
    • Label: “Needs Discussion” - (addressed in a triage meeting) - use liberally for either big or small tickets
    • “It’s better to give people more power: it’s actually helpful if people can overreach because it is an opportunity to establish where the limits really are and what purpose those limits have”

    Python⚓︎

    ADRs⚓︎

    <– Links –>