Differences

This shows you the differences between two versions of the page.

--- codebase:contributing [2024/09/28 15:58] – created - external edit 127.0.0.1
+++ codebase:contributing [2025/03/25 09:17] (current) – fponzi
@@ Line 1: / Line 1: @@
-====== Contributing ======
+====== Contributing to the tools ======
 TL;DR: engage maintainers early & often, be surgical in your changes, and write lots of tests.
@@ Line 13: / Line 13: @@
 To begin work on your change, fork this repository then create an appropriately-named branch to track your work. You will eventually submit a PR between your feature branch and the master branch of this repository, at which point developers & maintainers will review your changes. After integrating this feedback your PR will then hopefully be merged.
-When creating and submitting your changes, closely follow these guidelines: * **Be surgical:** What is the smallest diff you can make that still accomplishes your goal? Avoid the urge to fix unrelated stylistic issues in a file you are changing. * **Write tests first:** If you’re changing a specific part of the codebase, first ensure it has good test coverage; if it does, write a few more tests yourself anyway! Writing tests is a great way to learn how the code functions. If possible, submit your tests in a separate PR so their benefits can be realized immediately. We don’t fully subscribe to Test-Driven Development (TDD) but having good existing test coverage of a changed area is a prerequisite to changes being merged. * **Split up your changes:** If parts of your changes provide some benefit by themselves - like additional tests - split them into a separate PR. It is preferable to have several small PRs merged quickly than one large PR that takes longer to review. * **Craft your commits well:** This can require advanced git knowledge (see DEVELOPING.md). Treat your commits as forms of communication, not a way to bludgeon the codebase into shape. You don’t need to check this, but ideally the build & tests should pass on every commit. This means you will often be amending commits as you work instead of adding new ones.
+When creating and submitting your changes, closely follow these guidelines:
+  * **Be surgical:** What is the smallest diff you can make that still accomplishes your goal? Avoid the urge to fix unrelated stylistic issues in a file you are changing.
+  * **Write tests first:** If you’re changing a specific part of the codebase, first ensure it has good test coverage; if it does, write a few more tests yourself anyway! Writing tests is a great way to learn how the code functions. If possible, submit your tests in a separate PR so their benefits can be realized immediately. We don’t fully subscribe to Test-Driven Development (TDD) but having good existing test coverage of a changed area is a prerequisite to changes being merged.
+  * **Split up your changes:** If parts of your changes provide some benefit by themselves - like additional tests - split them into a separate PR. It is preferable to have several small PRs merged quickly than one large PR that takes longer to review.
+  * **Craft your commits well:** This can require advanced git knowledge (see DEVELOPING.md). Treat your commits as forms of communication, not a way to bludgeon the codebase into shape. You don’t need to check this, but ideally the build & tests should pass on every commit. This means you will often be amending commits as you work instead of adding new ones.
 When you open a PR against this repo, the continuous integration (CI) checks will run. These ensure your changes do not break the build & tests. While you can run most of these checks locally, if you’d like to run the CI at any time you can open a PR between your feature branch and the master branch of //your own// fork of this repo.