Call for proofreaders and beta testers for 19.03


#1

We get lots of contributors in Nixpkgs and NixOS who modify our source code. They are the most common type of contribution we receive. But, there is actually a great need for other types of contributions that don’t involve programming at all! For the benefit of new users, I am going to outline how you can easily contribute to the community and help make 19.03 the best NixOS release yet.

Proofreading

We have two different manuals in the NixOS/nixpkgs repo. One is for Nixpkgs, the set of all software. And the other is for NixOS, our Linux distro. Proofreading these manuals is important in helping new users learn about how our software works.

When you find an issue, you can do one of two things. The first and most encouraged is to open a PR on GitHub fixing the documentation. Both manuals are written in docbook. You can see the source for each here:

GitHub allows you to edit these files directly on the web. You can also always use your own Git client. For reference on writing in DocBook, I recommend reading through docbook.rocks.

An alternative if you are unable to fix the documentation yourself is to open an issue. We use the same issue tracker includes any issues with Nixpkgs/NixOS and can be accessed through GitHub Issue. Please be sure to provide a link to where in the manual the issue is as well as what is incorrect or otherwise confusing.

Beta testing

An alternative to proofreading is beta testing. There are a number of ways to do this, but I would suggest using VirtualBox. Some information on installing VirtualBox can be found online, but you should just need to set these NixOS options:

virtualisation.virtualbox.host.enable = true;

and add your user to the vboxusers group:

users.users.<user>.extraGroups = [ "vboxusers" ];

then rebuild your NixOS machine (sudo nixos-rebuild switch), and run this command to start virtualbox:

VirtualBox

Other distros have their own ways of installing VirtualBox, see Download VirtualBox for more info.

You can download an unstable NixOS .ova file directly here. (WARNING: this will be a large file, a little below 1GB).

Once downloaded, you can import this .ova file directly into VirtualBox using “File” -> “Import Appliance…”. Select the .ova file downloaded from above and click through a series of Next dialogs, using the provided defaults. After this, you can boot your NixOS machine by selecting it from the list on the left and clicking “Start”.

The next step is to just play around with the NixOS machine and try to break it! You can report any issues you find on the GitHub Issues tracker. We use the same issue tracker for both NixOS and Nixpkgs. Just try to make your issues as easy to reproduce as possible. Be specific on where the problem is and how someone else could recreate the problem for themselves.


pinned #2

#3

Asking a few logistical/process questions on the off chance I have some time to do any proofing:

  1. Is there a preference for how granular/aggregated proof edit commits and PRs should be, and how they should be organized (i.e. one commit/PR for all edits to a single section, or one commit to fix the “same” issue in many sections at once, etc.)
  2. Somewhat related; I assume manual content won’t stop shifting until the feature freeze/branch-off. If so, are there steps we can/should take to minimize merge issues (holding off until the feature freeze to start, turnaround/frequency guidelines, etc.)
  3. If we noticed anything that goes beyond proofing, is there already some place (discourse thread, wiki talk, living document, tracking issue?) we should note/mention it?

#4
  1. I think smaller edits are usually easier to review and get merged. You can always aggregate a bunch, but be prepared to make many changes.

  2. The manual usually gets update on master first. This makes things a little easier to handle as we just backport necessary changes to the stable branch. The manual is not specifically tied to any one NixOS version so it should not be super important when branching happens. We just want to get as much stuff in there for a good release.

  3. I would say GitHub issues are currently the best place for this. Especially with organization and structure.


#5

If you can edit your blog post (https://matthewbauer.us/blog/proofreaders.html) on this I suggest changing the 18.09 in the post title to 19.03, as it’s a little confusing.


#6

Thanks! Updated just now.


#7

While using the NixOS via the OVA within VirtualBox, is there a way to do the sudi nixos-rebuild build-vm to build an OVA in the shared result folder so that we may test the changes with ./result/bin/run-*-vm in a new VirtualBox VM running besides the initial VM?