Information organisation

Lix has a lot of information as a project, and we want to make it accessible in a way that it can be found later if necessary.

There are various tools for keeping information in the project, and they have different purposes

Chat

Chat is good for:

• Information that will be meaningless in hours
• Ephemeral discussions, in general

The chat is expected to move way too fast to follow. As such:

• Don't write things in chat that you expect to be found later
• If discussions of design happen, write them down, at least by copy pasting into a pad and adding the pad to the index
• If tips and tricks are discussed, please write them down
• Please do reviews on Gerrit so they are archived, rather than in chat
• Write things down in the log if they are expected to be found

The log pad (https://pad.lix.systems/lix-event-log [private])

The log pad is intended as a tool to communicate what is going on in general, without having to have everyone pay attention to chat too much.

It should be used for:

• Updates on what we are working on, in addition to chat

It should not be used for:

• Actually notifying people, necessarily

Pad (https://pad.lix.systems [private])

We anticipate that the pad service will be semi-permanently private by default, since it doesn't support ACLs.

The pad is good for:

• Sketching out drafts of documents that aren't ready yet
• Planning private things
• Generally getting people on the same page about things in active design, making what might be meeting notes, or similar.

The pad is not good for:

• Information that should be available to users (unless it is planned to move)
• Information that is not actively changing

N.B. For users who aren't in the Lix core team, the service returns 500 when you attempt to login. This is a known issue that can't be fixed.

Wiki (https://wiki.lix.systems)

The wiki is good for:

• Development process information, like you would find on https://rustc-dev-guide.rust-lang.org/ for the Rust compiler, for instance.
• Design documents

The wiki is not good for:

• User facing documentation
• Documentation that deserves to be reviewed
• Actively writing a document in real time with others

Markdown files in the Lix repo

Markdown files in the Lix repo are good for:

• Maintaining things that are tied directly to the code
• Documentation that needs to be reviewed
• User facing documentation

Markdown files in the Lix repo are bad for:

• Quickly iterating on things
• Design documents

Forgejo issues (https://git.lix.systems)

Our primary issue tracker is Forgejo issues.

We are currently attempting to use the Forgejo project boards feature to communicate what people are working on; it may be replaced with better Kanban software in the future. When making project boards on Forgejo, make them on the lix-project organisation unless they are strictly contained within one project.

The issue tracker is good for:

• Actionable work
• Bugs

The issue tracker is not good for:

• Dreams or otherwise not actionable information that is a long term goal
• Private information
• Information that needs to be found later, design documentation

Where to put an issue

• lix-project/lix, if it is contained within Lix (but is not more appropriate to put in the installer e.g.)
  • If it is an upstream bug, tag its equivalent lix-import on https://git.lix.systems/nixos/nix, and get someone with the bot token to run the issue import script in maintainers/issue_import.py. (FIXME: someone ought to put that on a cron job)
  • Please never file issues on our Nix mirror.
• lix-project/installer, if it is the installer
• lix-project/web-services, if it is infrastructure related
• lix-project/meta, if it does not fit anywhere obvious and you just need it to put it on a board
• lix-project/nixos-module, if it is a packaging bug in that specifically

Gerrit (https://gerrit.lix.systems)

Gerrit is good for:

• Reviewing code
• Maintaining a record of code reviews

Gerrit is not good for:

• Persisting information in a discoverable way to anyone in the future
• Documentation