Skip to main content

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
Back to top