Auxolotl Laboratories

General
1

Hey there everyone! If you’ve all noticed a bit of a slowdown on events, you’d be correct! I have been focused on building up an alternative library to the one in NixPkgs and now have an initial version working with a good amount of helpers and a functioning module system. That’s right, no more NixPkgs lib needed*!

* There will likely be gaps since I have limited the scope of the library, but we can add to it as needed.

As a part of working on this I wanted to introduce a proper place for experiments where we can build things up that aren’t fully formed just yet. As such, I am introducing Aux Labs. With labs, we can avoid cluttering the organization with intermediate repositories for experiments. It also provides an outline for communicating the stages of a given experiment:

Phase Description
Idea An idea exists to solve a problem we currently have with Aux. Send a pull request to this repository creating a new directory for your experiment. The directory should contain a README.md file explaining the purpose of the experiment.
Iteration Work on the experiment is done to solve for unknowns and come up with a good solution for the original problem. It may also be helpful to collaborate with others for feedback.
Proposal The experiment has been satisfactorily completed and is ready to be considered for official adoption by the project. Discussion with the relevant Special Interest Group should take place to handle the transition of the project out of the lab and into its own repository.
Adoption The experiment has been adopted and is now a part of Aux! The experiment should be moved to its own repository and the original experiment directory should be deleted.

Aux Lib is currently in the Iteration phase and can be found here. While we do not have any generated documentation, one goal of this project is to provide more prominent and easily parseable documentation. To do so, I have been using the following format:

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.
    ##
    ## @type Int -> String
    func = x: builtins.toString x;
in
    # ...

The project is also set up with minimal testing infrastructure. I’ve taken the “good enough” approach here since this is bootstrapping the very foundation of the ecosystem. Eventually it would be nice to have a better testing framework for Nix code. You can see each function’s associated tests in the colocated *.test.nix files such as src/attrs/default.test.nix. To run these tests you can execute ./test.sh from within the lib/ directory.

With all of this announced, what is there to do then? Plenty! Here are some concrete things I am looking for help on:

  • Documentation: Adding proper documentation comments to the remaining instances marked by “TODO: Document this.”
  • Testing: Adding additional tests for functions which do not currently have them or for functionality that is not being tested yet.
  • Documentation Generation: We should now be able to parse the library and build documentation from each utility’s doc comment.
  • Filling Gaps: We don’t want to add everything that NixPkgs’ lib has, but there are certainly still things we need.
  • Users: We need people to try using the library and help to find its rough edges so we can resolve any issues or usability problems.
20 Likes
2

Is it a good idea to have several mutually independent experiments in the same single repository?

My rule of thumb of whether stuff belongs in the same Git repository (other when you kinda need it all together because of explicit dependencies between the files) is whether you need to be able to get back consistent revisions of all the things in there together, e.g. due to common implicit interfaces where version numbers or dependency management would be impractical or in face of conceptually necessary circular dependencies.

Stuff (or separate clusters of stuff) without any inter-dependencies and without the need of overarching common revisions however can (and often should) go into separate repositories.

That way, when an experiment matures into a stable project, one can simply move its whole repo to another namespace, preserving all its history (including the experimental stages), without having to git filter-branch or git filter-repo or similar arcane steps.

With labs, we can avoid cluttering the organization with intermediate repositories for experiments.

To keep the top-level namespace of a GitLab group clean in this regard, I’d simply use a dedicated subgroup for experimental repos. Now, GitHub doesn’t have nested group namespaces like GitLab has, so that’s not an option, so that might seem to force us to use a single repo for experiments. But maybe we could just have a separate GitHub “organization” for the experimental repos? (Can GitHub organizations maybe inherit members and permissions from other GitHub organizations, so that we wouldn’t have to maintain those for both? If not, this can surely be approximated by automating synchronization using a recurring job and the GitHub REST APIs.)

2 Likes