Contributing to Nailpit#

Nailpit is software written by humans for humans. Or at least, software written by humans to deter (misbehaving) machines. As such, all contributions should not be using AI in any form. There is no pressure to "ship it" here, no investor baiting, no tech hyping. This project is a temple to the art and joy of coding, and thus should be enjoyed for what it is, not delegated to an unthinking machine. There is no expectation of perfection, only for understanding and for doing one's best.

That's the starting point: Be Human

From there, contributing is as simple as creating a fork of this project, get it to compile on your local environment, creating a branch, then publishing the branch once you are done. Create a pull request (PR) and then hope for the best!

To contribute, there is the expectation that you are at least familiar with:

• git
• Rust and its toolchains, cargo, etc
• HTML and web stuff.

If the above are not things you are familiar with, then please take the time to learn them. There are resources for this.

Implementing a feature/improvement#

Before starting work on a feature, check if there isn't an open issue or PR already. If there's something on the roadmap that hasn't been done, or if there isn't and you feel it would be a good addition, feel free to take up on that task. First, create a specific issue for that feature and try to outline the following:

• Feature to be worked on, explaining why it is needed
• (Optional) Outline the proposed implementation, or implementations if soliciting wider feedback.
• If it is a large feature, outline smaller steps for completing the work.

If the issue is reviewed/discussed and the consensus is to go forward, then feel free to create a PR. You can also create draft PRs if you wish to take more exploratory work upfront in order to get more information on a given approach. Such work should still be pinned to an issue in order to track progress.

PR's should have a clear and concise title outling the feature. The PR description should then provide an explanation of the feature implementation, and also how to test it, as well as any breaking changes. If the PR implements a feature completely, ensure there is a link back to the issue stating "Closes #issue number"

Once the PR is reviewed and it passes all CI checks, it will get merged and the feature issue updated/closed.

Submitting bug fixes#

If a bug is found, create an issue detailing the following:

• Nailpit version (branch, commit, etc)
• Hardware/OS versions (example, Raspberry Pi 5 8GB, Debian arm64)
• Situation which bug was found
  • Expected behaviour
  • Actual (buggy) behaviour

Include a minimal reproducible example of the code for showcasing the bug if it involves library/crate code, else include the configuration that triggers the bug if it is for the application itself.

Ensure the bug issue is created first before submitting a PR to fix the bug. This is to help track the issue and also any impact. The PR should reference the original issue with "Closes #issue number".

Documentation#

All submitted code should have some documentation in place. It does not need to be extensive, but it should explain and detail the implementation, how to use new APIs/methods, etc. More extensive documentation can be added later, but such efforts should have a dedicated issue to track the progress. All documentation should not be written/generated by LLMs. Please take the time to write it yourself. Any poor english/grammar can always be fixed through code review. It's more important to have true understanding of what you are writing about and being able to communicate very intricate technical details, nuances and concepts that LLMs are utterly inadequate with.

Unsafe code#

If you are not completely comfortable writing unsafe code, then don't. Stick to safe rust. If you are comfortable with writing unsafe rust, stick to safe rust. Break out the unsafe only when there is reason for it, and be prepared to document that reasoning extensively. It is important to get it correct, both for testing with Miri, but to ensure any future contributors can come in and understand what can be touched and what shouldn't.

If in the future, Rust comes out with a feature that allows existing unsafe code to be written in safe rust without perf regressions, then that code will be refactored to safe rust.

The idea here is we only employ unsafe code where necessary. Make use of tools like Miri to check any unsafe code, and be thorough with tests to ensure all corner cases are caught.

Where to go from here?#

Still interested in contributing? Check out the roadmap here if you need a high-level view of what the goals are and what needs to be worked on. That should give you a general idea of what the state of the project is and what to take on in terms of tasks.

But why no AI?#

As the maintainer of this project, I expect any and all contributors to truly understand the code they are contributing. What does it do? What are the pros of the approach? What are the cons and trade-offs? I am not expecting super high quality code, but I am expecting code that has been crafted with full understanding of that implementation. This has benefits for both myself a maintainer and for you as a contributor:

1. Code that is understood is more easily maintained. Knowing what are the edge-cases helps narrow down sources of bugs and providing suitable fixes, and also allows for future work to be planned around the provided code.
2. Code that is understood is less likely to need to be constantly refactored, reducing churn and tech-debt.
3. Code that is understood is easier to write accurate documentation for, and provide examples for. And during code review, you'll be able to explain what you've done more confidently.

By using an AI/LLM to generate the code, you are trading this understanding for speed and convenience. But for Open Source Software, what matters more is providing code that others can understand and maintain. You might contribute a feature, but that feature will then need to be maintained by myself and others in the future, so ensuring everything is clear and well documented is of vital importance. If you can't code a feature without the assistance of an AI tool, then you can't code with any level of understanding. But it isn't hard to do so! It just might take longer (and you might learn a few things in the process by doing so).

Other reasons for not wanting AI/LLM generated contributions is for legal reasons (questions regarding copyright & licensing violations on data which these models are trained on), and ethical reasons (such as the power consumption and exorbitant water requirements these models require). Best to avoid all that by just not accepting AI/LLM generated contributions.