From 6ec6899793b941f59038cdd18323717244bc98eb Mon Sep 17 00:00:00 2001 From: voidarc Date: Sun, 16 Aug 2026 10:57:59 +0100 Subject: [PATCH] added CONTRIBUTING.md --- CONTRIBUTING.md | 223 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e5b75a9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,223 @@ +# CONTRIBUTING + +## General format + +All emails regarding this repo (or another) should have a subject prepended with the +following: + +```text +[GIT] [voidarc/nixos] (request type) +``` + +The content of the second set of brackets should be replaced with the specific submodule +or repo that is being referred to. For example, in the case of a quickshell bug, it should +contain `voidarc/quickshell`. + +In general, for most requests, I also implore you to include a github username (or +equivalent, codeberg, gitlab, etc.) so that I have a frame of reference for you as a +person, and also so that you can be credited in any resulting commits. Depending on +scenario, this requirement can be waived, or substituted for a reddit account or +something. + +The third set of brackets pertains to the subject proper, and should only reasonably +contain `issue`, `patch` or `feature`. If you believe that your request does not fit into +any of those categories, then feel free to do whatever you want within reason. + +## Issues + +Issues are restricted to bugs or otherwise not fixed problems in the code. If it is an +upstream bug, ie one not caused by my specific config, please don't send me a complaint +about it, refer to the source app. The subject for an issue should be formatted as such: + +```Text +(prefix) (module type) (specific module) - (description of issue) +``` + +The prefix shoud be formatted as above. In the case of an issue pertaining to another +repo, the module type and module name may be omitted, unless it is an issue with the +dendritic module implementation, in which case the repo in the subject should be this one. + +The module type should match the repo's folder structure, being one of `feature`, +`system`, `attr/attribute` or `host`. Self explanitory. Doesn't have to be an exact match. + +The specific module should be the name of the module itself, not just the directory that +contains it, due to the fact that some directories and files contain multiple modules. In +the case of a file containing both a package and a module, favour the module that +implements the package, and not the package itself (`self.nixosModules` rather than +`self'.packages`). + +The description should follow standard conventions, as you would report on other +platforms. Don't make it stupidly long, common sense required. + +The body of the email should be reminiscent of a github issue, and contain the following +items in roughly the presented order: + +- Clear description of the issue (and why it's an issue in the first place, and not + personal preference) +- Step by step instructions on how to replicate the given issue +- Step by step instructions detailing what you believe the behaviour should be +- Any attempts to fix the issue, or references to suspected code that may be causing the + issue + +If you have attempted to fix the issue, or altered the code, please refer to the next +section + +## Patches / Contributions (Pull requests) + +Patches are for altered code that you would like me to review and possibly add to the +codebase. Most of the time, these should be for issues that you have encountered using the +repo, not new features entirely. If a patch doesn't fit an issue, is mostly or fully AI +generated, or otherwise doesnt fit the repo, it will be rejected. + +The format here is similar, but with a few key differences. The type of request should +obviously be patch, and the rest should be identical to the previous type, containing +module type, name, and a short description of the issue. + +The body should also follow similar beats, having a breakdown of the issue and detailing +the intended behaviour. Beyond the detailing portion, there are some other specific things +that are required for issues in particular. + +- A description of whatever alterations have been made to the code +- Some form of username so that, in the event of a merge, you can be credited properly +- A disclosure of how much or little AI was used in the creation of the patch. For + completeness, even if no AI is used, please include "No AI was used" anyway, it is not + implied. + +A git patch file should be attatched to the email, not a link to a github repo or +something else. Any "patch" email with no attatchments will probably not be looked at any +further than the issue section. For patches, please refer to the +[Formatting Rules](#formatting-rules) + +Both issues and patches are on a first come first serve basis. Because there is no public +forum (I'm sure as hell not maintaining one), if someone submits an issue or patch, even +if someone else independantly discovered the bug, the first person will most likely be +credited for that issue. + +If you have previously opened an issue, and wish to make a patch for the same issue, reply +to the initial issue email, and prefix the subject with `PATCH:` instead of the usual +`RE:` or whatever your email client chooses to prepend. The rest of the subject should +remain the same. The email should then contain the patch-specific sections, found above. +Don't bother re-iterating the issue. + +## Feature Requests + +Feature requests are for anything that doesn't already exist or doesnt otherwise fall into +the previous categories. These are more freeform, and could come in the form of a useful +app, a better way of managing something, or a better replacement for something that is +already in the repo. Most importantly, this is NOT somewhere to shill an app you +vibe-coded. Any AI generated apps will be rejected out of principle. + +Headers should follow this structure, but, again, this is lenient: + +```text +(prefix) - (Feature type) - (App name): (description) +``` + +The feature type, as before, should be one of the given folders in the repo. Generally, +this will be a `feature` for a new app, but could be `system` for a new driver or +`attribute` for a new collection of packages. If it is more general than any of those +categories, or smaller in scope than an entire feature, use the feature type `other`, and +detail what you are requesting (other should be used if you are just requesting a singular +package be added to the system, for example). + +Instead of following a fixed structure for the body, it is up to you to make a case for +whatever you are suggesting. Whatever that entails is up to you. It could be use cases, it +could be reasons it is better than whatever I am using. Be as verbose or as minimal as you +wish, but keep in mind that the better your argument is, the more likely I am to accept +your contribution. Again, if you wish, you can leave a username so that you can be +correctly credited if I decide to include whatever you suggested. + +If you are suggesting a new feature, app or otherwise, you may also choose to make a basic +or full module implementing that feature, and then attach that to the email in the form of +a patch. Refer to the [Formatting Rules](#formatting-rules) for further instruction on how +to write your code. + +Please also leave references for whatever it is you're suggesting, not just the name of +the app. This could come in the form of documentation, a homepage, or the link for its +github. In general, if an app has none of these things, or is closed source in any +capacity, it will not be accepted. + +## Formatting rules + +Formatting in this repo should attempt to be standard to whatever I am using. For ease of +use, either refer to or use my nvim config (`#nvim` output for this repo, refer to the +README for how to run it). This prevents ugly git histories with commits specifically for +formatting etc. + +### General rules + +When submitting a patch, there should be no merge conflicts with the current HEAD at the +time of creation. It is a good rule of thumb to pull from remote before making a patch, +incase behaviour changes. + +If there are commits pushed between the time you send a patch and the time it is reviewed, +any resulting merge conflicts are not your fault, and therefore will not be treated as +such. Don't resubmit the same patch because there are new commits on remote, when patches +are reviewed they are inserted at the point at which they were created, not on top of +newer commits. + +#### Branches + +All patches should be mergable to the main branch, ie not have a patch for the `feature-x` +branch or some nonsense. I do not have your git history, and therefore don't have whatever +branch you created on my machine. In general, most changes should be restricted to one +commit, so that crediting is easy. + +If a change is more than one or two commits, make a new branch, make the changes that you +want, then merge to the latest head before submitting a patch. When merging back to main, +please use a merge commit instead of fast forwarding or clobbering the branch. This makes +it easy to see who made what changes in the git history, and keeps blame easy to read. +This merge commit will be where your credit goes. If you submit a patch that contains a +load of commits on the main branch, the chances I accept the patch are very low. + +### Code + +There are many types of code in this repo, so if there is any confusion, either refer to +the config that I am using in nvim, or send me an email asking me how to handle it. + +#### Nix + +For starters, all nix code should be formatted with +[Alejandra](https://github.com/kamadorueda/alejandra). If you choose to format your code +with nix-fmt or something else, chances are I won't refuse it, but I will overwrite your +commits with a formatted version. To format the entire repo properly, run the following +command: + +```bash +nix-shell -p alejandra --run "alejandra ." +``` + +This will recursively check and format all `.nix` files in the repo, which is what I want. + +As a secondary requirement, try to follow the already set out conventions that are on +display in this repo, as well as the conventions of dendritic nix. A few examples: + +- All top level objects should be merged into one unless there is a good reason for it +- The first item in a module should be the module definition (`flake.nixosModules.xyz`) +- All modules should be portable unless there is a good reason for it +- Modules should reference eachother through `self.nixosModules` instead of relative + paths, which should be avoided in most scenarios +- In general, if a package is available in nixpkgs, an input need not be added. This rule + differs case-by-case due to versioning differences. + +#### Markdown + +All markdown files should be formatted using prettier, with the settings provided in this +repo. For reference, the rules are: + +- 90 characters maximum, excluding code blocks +- word wrapping +- tab width of 2, as well as replacing spaces with tabs + +#### Other languages + +For one-off config languages (think `kitty.conf`), no formatting is needed. Whitespace can +be added at the programmer's disgression. + +For standard structured languages, such as json, yaml or toml, if there is an available +prettier formatter, then it should be used. In general, tabwidth should be 2 and spaces +should be used across the board. Don't use some esoteric formatter just to be special. + +For actual programming languages, like qml or lua, either use the provided formatter, such +as `qmlformat`, with the settings configured, or refer to my nvim config (in this case I +use `stylua` with the default settings)