Contributing to `bitomc`
=====================
Suggested Steps
---------------
1. Find an issue you want to work on.
2. Figure out what would be a good first step towards resolving the issue. This
could be in the form of code, research, a proposal, or suggesting that it be
closed, if it's out of date or not a good idea in the first place.
3. Comment on the issue with an outline of your suggested first step, and
asking for feedback. Of course, you can dive in and start writing code or
tests immediately, but this avoids potentially wasted effort, if the issue
is out of date, not clearly specified, blocked on something else, or
otherwise not ready to implement.
4. If the issue requires a code change or bugfix, open a draft PR with tests,
and ask for feedback. This makes sure that everyone is on the same page
about what needs to be done, or what the first step in solving the issue
should be. Also, since tests are required, writing the tests first makes it
easy to confirm that the change can be tested easily.
5. Mash the keyboard randomly until the tests pass, and refactor until the code
is ready to submit.
6. Mark the PR as ready to review.
7. Revise the PR as needed.
8. And finally, mergies!
Start small
-----------
Small changes will allow you to make an impact
quickly, and if you take the wrong tack, you won't have wasted much time.
Ideas for small issues:
- Add a new test or test case that increases test coverage
- Add or improve documentation
- Find an issue that needs more research, and do that research and summarize it
in a comment
- Find an out-of-date issue and comment that it can be closed
- Find an issue that shouldn't be done, and provide constructive feedback
detailing why you think that is the case
Merge early and often
---------------------
Break up large tasks into multiple smaller steps that individually make
progress. If there's a bug, you can open a PR that adds a failing ignored test.
This can be merged, and the next step can be to fix the bug and unignore the
test. Do research or testing, and report on your results. Break a feature into
small sub-features, and implement them one at a time.
Figuring out how to break down a larger PR into smaller PRs where each can be
merged is an art form well-worth practicing. The hard part is that each PR must
itself be an improvement.
I strive to follow this advice myself, and am always better off when I do.
Small changes are fast to write, review, and merge, which is much more fun than
laboring over a single giant PR that takes forever to write, review, and merge.
Small changes don't take much time, so if you need to stop working on a small
change, you won't have wasted much time as compared to a larger change that
represents many hours of work. Getting a PR in quickly improves the project a
little bit immediately, instead of having to wait a long time for larger
improvement. Small changes are less likely to accumulate merge conflict. As the
Athenians said: *The fast commit what they will, the slow merge what they
must.*
Get help
--------
If you're stuck for more than 15 minutes, ask for help, like a Rust Discord,
Stack Exchange, or in a project issue or discussion.
Practice hypothesis-driven debugging
------------------------------------
Formulate a hypothesis as to what is causing the problem. Figure out how to
test that hypothesis. Perform that tests. If it works, great, you fixed the
issue or now you know how to fix the issue. If not, repeat with a new
hypothesis.
Pay attention to error messages
-------------------------------
Read all error messages and don't tolerate warnings.