Giters

bumblefudge / process

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Spruce Development Process

This repository describes the contribution rules, guidelines, and procedures that collectively form the development process used at Spruce Systems, Inc. All engineers contributing to Spruce Systems, Inc. projects are expected to practice and uphold the Spruce Development Process, henceforth known as "the process". It is completely fair and even encouraged to call out violations of the process, from new employee to CEO. PRs to this repository are welcome.

Process updates

Process updates are currently reviewed, approved, and merged by @wyc.

Repository etiquette

We use the git version control system hosted on GitHub, including its features Issues, Pull Requests (PRs), and Actions.

Working in branches

All work should be completed in separate branches that are short, descriptive, dash-separated, and prefixed with feat/ (for features), bug/, or hotfix/.

Examples of good branch names:

feat/refactor-did-resolution
hotfix/parse-utf8-jwt
bug/dup-ctx-caching

Examples of bad branch names:

my-new-feature (no prefix)
my-new-feature-1 (adding arbitrary '1' to branch name)
feature-set/add_one_function (not dash-separated, invalid prefix)
bug/the-loop-that-runs-one-too-many-times (too verbose)

It is preferred that you work in the open from your first commit using the [WIP] PR title prefix and use the task list as recommended. Push your changes to your branch early and often, force pushing significant progress as is convenient. This way, the bus factor is reduced, and you are communicating your changes to other collaborators in closer to real time.

Commits should be well-formed

Commits should all be well-formed as soon as you remove the [WIP] PR title prefix (see the next section on PRs) and request reviewers. Please see Tim Pope's note about commit messages. Furthermore,

  • Make sure you explain why these changes are necessary and their underlying goal.
  • It is okay to have shorter commit messages (even 1-line messages) for smaller changes.
  • Each commit should reflect one logical change and not many separate ideas.
  • Please add references to issue and pull request numbers to the bottom if your commit message if they are relevant.

Never push to the main branch

This would render peer review impossible, and the repository security settings shouldn't even allow you to do this.

Creating pull requests

Pull requests are meant to communicate your changes to other developers so they can peer review and approve merging. They should be written with this audience in mind.

  • Pick a title that succinctly explains your changes.
  • Summarize what your one or more commits will do and their purpose.
  • Include relevant issue numbers and other PR numbers.
  • Do not create massive PRs of high hundreds of lines of changes before getting permission from the repository owners. These PRs are difficult and painstaking for reviewers to review. Consider splitting your work into independent PRs. Exceptions typically granted permissions include major refactorings, hotfixes, and independent submodules, but you should ask the repository owners before creating your changes.
  • It is okay to write a PR dependent on another PR (typically branched off), but make sure you include this in the message.
  • Include any hints around specific areas or tricky codepaths that you'd appreciate extra attention.
  • Prefix your PR with [WIP] if it is a work in progress and not yet ready for review and merging. Consider using the task list feature to communicate your ongoing progress.
  • When your changes are ready for review and merge, remove the [WIP] prefix and assign at least one reviewer including a repository owner. Only repository owners may merge PRs.
  • If you are given feedback and are requested to change your work, ensure that the commits remain well-formed, and force push to your branch if necessary to keep a clean series of commits.
  • Always prefer rebasing your branch to main to ensure a linear history. If you believe a merge commit is a better solution, obtain permission from the repository owners to do so.

Reviewing and merging pull requests

Timely peer review is critical to achieving high quality. When you are requested to review a PR, you are expected to provide a review within 2 business days by default. This expectation can change if the PR is internally reprioritized or if you receive explicit approval from a repository owner, e.g., by emailing or messaging them about it directly. Additionally, as a reviewer,

  • If a PR is too big to review effectively, do not hesitate to ask the author to refactor into smaller PRs if independent changes are readily identifiable.
  • Make sure you run the code and tests locally, and that it passes any existing CI/CD, style checkers, and other automated build process tools.
  • Look for test cases to cover new changes introduced. Request more test cases if they are low hanging fruit or a new complex feature lacks testing.
  • For smaller PRs, using the "Add single comment" feedback is acceptable. For larger ones, begin a review, add your comments, and ensure that you click the "Finish review" button so your feedback is visible.
  • If the commit messages, PR format, or branch conventions violate this process, do not hesitate to ask the author to rework their contributions with a link to this repository.
  • If the PR adds new dependencies, check the dependencies for inclusion worthiness.
  • Ensure that contributor licenses are signed (should be automatically checked by CLA bot when it is live) and that the PR does not introduce license changes, such as by modifying the license directly or including non-compatible licensed dependencies.
  • Anyone can review a pull request, and this is encouraged. Simply add yourself to the reviewers even if you were not requested to review. If you are not responsive, then you will be removed.

For additional information reviewing the actual code, refer to this code review documentation.

Documentation

Here are the guidelines for documentation at Spruce:

  • Documentation is just as important as code. We work on open source software projects, and for many, the documentation is the user interface. Bad documentation means a bad product, and bad products have no business at Spruce.
  • When you make code changes, ensure that the documentation is up to date. Even better if the documentation is testable. This may mean that the documentation is derived from code files or vice versa, such as in literate programming. This means that we should prefer documentation to be tested in our continuous integration processes where possible.
  • A report of incorrect documentation should be taken as seriously as a bug in the codebase. This is the same as breaking a key promise to our users.
  • Prefer "zero-to-hero" approaches to documentation, in which we assume users start with a bare minimum setup without any developer tooling. Imagine a fresh operating system install and either drop hints or explicitly detail how a user should configure their environment from a clean slate. It is acceptable to refer to popular setups, but these should be aligned with the developer user base for our products.
  • Multi-operating system support should be the default assumption, and explicitly state if you assume a specific base operating systems for your documentation, such as Debian 10, Ubuntu 20.04 LTS, RHEL 8, FreeBSD 12.2, Windows 10, or MacOS 10.14.

About