claire/lib
1
0
Fork 0
forked from auxolotl/lib
Code Pull requests Activity

Hard-wrap the README to 80 columns (#12)

Browse source 
The text of this is unchanged **except** I added a sentence saying to please keep the README wrapped to 80 columns. I am proposing this as a style rule (only for Markdown files).o

The reasoning here is that the README is the onboarding information that newcomers to the project need, and it should be readable via as many different approaches as possible.

While many people approach new codebases by browsing the web, some of us still do the old thing of cloning the repo and looking for descriptive files within it, and for those people we should try to work on the widest variety of terminals we can. 80 columns has been a lowest-common-denominator width since the 70s, so it makes a good target for this purpose.

I'm not hurt if people disagree, I just thought I'd offer this :)

Co-authored-by: Jake Hamilton <jake.hamilton@hey.com>
Reviewed-on: auxolotl/lib#12
Reviewed-by: Jake Hamilton <jake.hamilton@hey.com>
Co-authored-by: Irene Knapp <ireneista@irenes.space>
Co-committed-by: Irene Knapp <ireneista@irenes.space>
This commit is contained in:
Irene Knapp 2025-10-18 22:25:47 +00:00 • committed by Jake Hamilton
parent 0f5182ff0d
commit 06b458ea7a
1 changed files with 57 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

102
README.md
View file

@ -1,21 +1,22 @@
# Aux Lib
Aux Lib is intended to be a replacement for NixPkg's `lib` with stronger constraints around naming,
organization, and inclusion of functions. In addition to replacing library functions, Aux Lib also
defines a revamped version of the NixOS Module system intended to make it easier, more approachable,
and intuitive.
Aux Lib is intended to be a replacement for NixPkg's `lib` with stronger
constraints around naming, organization, and inclusion of functions. In
addition to replacing library functions, Aux Lib also defines a revamped
version of the NixOS Module system intended to make it easier, more
approachable, and intuitive.
## Usage
The library can be imported both with and without Nix Flakes. To import the library using Nix Flakes,
add this repository as an input.
The library can be imported both with and without Nix Flakes. To import the
library using Nix Flakes, add this repository as an input.
```nix
inputs.lib.url = "https://git.auxolotl.org/auxolotl/lib/archive/main.tar.gz";
```
To import the library without using Nix Flakes, you will need to use `fetchTarball` and import the
library entrypoint.
To import the library without using Nix Flakes, you will need to use
`fetchTarball` and import the library entrypoint.
```nix
let
@ -29,22 +30,25 @@ in
## Development
To contribute to the project, we accept pull requests to this repository. Please see the following
sections for information on the appropriate practices and required steps for working on Aux Lib.
To contribute to the project, we accept pull requests to this repository.
Please see the following sections for information on the appropriate practices
and required steps for working on Aux Lib.
### Documentation
We want our code to survive in the world, but without proper documentation that won't happen. In
order to not lose knowledge and also make it easier for others to begin participating in the
project we require that every function have an appropriate documentation comment. The format for
these comments is as follows:
We want our code to survive in the world, but without proper documentation
that won't happen. In order to not lose knowledge and also make it easier for
others to begin participating in the project we require that every function
have an appropriate documentation comment. The format for these comments is as
follows:
```nix
let
## This is a description of what the function does. Any necessary information can be added
## here. After this point comes a gap before a Hindley-Milner style type signature. Note
## that these types are not actually checked, but serve as a helpful addition for the user
## in addition to being provided in generated documentation.
## This is a description of what the function does. Any necessary
## information can be added here. After this point comes a gap before a
## Hindley-Milner style type signature. Note that these types are not
## actually checked, but serve as a helpful addition for the user in
## addition to being provided in generated documentation.
##
## @type Int -> String
func = x: builtins.toString x;
@ -54,9 +58,10 @@ in
### Testing
All functions that are added to the project should include tests. The test suites are located
next to their implementation in files ending in `.test.nix`. These tests should ensure that
the library behaves as expected. The typical structure of these test suites is:
All functions that are added to the project should include tests. The test
suites are located next to their implementation in files ending in
`.test.nix`. These tests should ensure that the library behaves as expected.
The typical structure of these test suites is:
```nix
let
@ -74,15 +79,15 @@ in
}
```
Successful tests will return `true` while failing test will resolve with `false`. You can run
all tests with the following command:
Successful tests will return `true` while failing test will resolve with
`false`. You can run all tests with the following command:
```shell
./test.sh
```
If you want to run a specific test suite, you can run the command, specifying the directory
to the tests file:
If you want to run a specific test suite, you can run the command, specifying
the directory to the tests file:
```shell
./test.sh $namespace
@ -96,34 +101,41 @@ For example, to run the tests for only `attrs`, use the following command:
### Formatting
> **Note:** To keep this flake light and keep its inputs empty we do not include a package
> set which would provide a formatter. Instead please run `nix run nixpkgs#nixfmt-rfc-style`
> until an improved solution is available.
> **Note:** To keep this flake light and keep its inputs empty we do not
> include a package set which would provide a formatter. Instead please run
> `nix run nixpkgs#nixfmt-rfc-style` until an improved solution is available.
All code in this project must be formatted using the provided formatter in the `flake.nix`
file. You can run this formatter using the command `nix fmt` (not currently available).
All code in this project must be formatted using the provided formatter in the
`flake.nix` file. You can run this formatter using the command `nix fmt` (not
currently available).
Additionally, please keep Markdown files such as this one hard-wrapped to a
width of 80 columns.
### Code Quality
In order to keep the project approachable and easy to maintain, certain patterns are not allowed.
In particular, the use of `with` and `rec` are not allowed. Additionally, you should prefer the
fully qualified name of a variable rather than creating intermediate ones using `inherit`.
In order to keep the project approachable and easy to maintain, certain
patterns are not allowed. In particular, the use of `with` and `rec` are not
allowed. Additionally, you should prefer the fully qualified name of a
variable rather than creating intermediate ones using `inherit`.
### Adding Functionality
Before adding new features to the library, submit an issue or talk the idea over with one or
more of the project maintainers. We want to make sure that the library does not become bloated
with tools that aren't used. Some features may be better handled in a separate project. If you
do get the go-ahead to begin working on your feature, please place it in the library structure
similarly to how existing features are. For example, things dealing with strings should go in
`src/strings/default.nix`.
Before adding new features to the library, submit an issue or talk the idea
over with one or more of the project maintainers. We want to make sure that
the library does not become bloated with tools that aren't used. Some features
may be better handled in a separate project. If you do get the go-ahead to
begin working on your feature, please place it in the library structure
similarly to how existing features are. For example, things dealing with
strings should go in `src/strings/default.nix`.
Additionally, you should prefer to group things in attribute sets for like-functionality. More
broad categories such as `strings` and `lists` are helpful, but scoped groups for things like
`into`, `from`, and `validate` also make the library more discoverable. Having all of the
different parts of the library mirroring this organizational structure makes building intuition
for working with the library much easier. To know when to group new things, consider the
following:
Additionally, you should prefer to group things in attribute sets for
like-functionality. More broad categories such as `strings` and `lists` are
helpful, but scoped groups for things like `into`, `from`, and `validate` also
make the library more discoverable. Having all of the different parts of the
library mirroring this organizational structure makes building intuition for
working with the library much easier. To know when to group new things,
consider the following:
- Would your function name be multiple words like `fromString`?
- Are there multiple variants of this function?