nixos/CONTRIBUTING.md

CONTRIBUTING

General format

All emails regarding this repo (or another) should have a subject prepended with the following:

[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:

(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

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:

(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 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. 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:

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)