Minutes from SIG: Documentation meeting on 2024-05-11

Attendees:

  • minion (Skyler Grey)
  • coded (Samuel Shuert)
  • liketechnik (Florian)
  • dfh (Olly)
  • nova

Agenda

  • Approval/revision of agenda
  • New people introductions, if any new people
    • [Florian] Using NixOS for 2.5 years, generaly interested in programming and linux. Interested in docs because it’s difficult to get right, big dealbreaker for using software.
  • Translation discussion
    • Issues in setting up weblate
      • Might take longer as weblate OS plan requires you to be around for 6+ months. May have to host ourselves.
    • [dfh] How do we remind translators that things need translating
      • could force PR to update translations
      • could ping translators when we update things
        • [minion] I think this is a good idea
        • minion to get a list of translators to ping
      • [florian] Could have a “this is outdated” message on old translated pages
        • [coded] this is a good call, maybe add a version number in the translation file to say where it is version wise in relation to english
        • [minion] I like that because it doesn’t mean that as soon as we update something, everything reverts to English
  • Nextcloud calendar
    • it exists!
    • put your events in there!
  • Wiki pages
    • community pages
      • “how is it run?”, “onboarding instructions”, “what to find whereS”
      • [minion] we could put this in contributing/sigs-and…
      • [coded] do we want to move this out to somewhere else?
        • [dfh] I agree, I think it’s too far in the tree
        • [dfh] maybe we should even separate SIGs and Committees?
        • [minion] Agreed, it’s too far down in contributing
      • [minion] things that people who want to interact with the commitee need to know vs things that you need to know to use your system
    • [minion] anything else that we should work on in the next week
      • getting started → split some stuff into an installation guide?
      • [dfh] nix to lix migration page
        • [minion] is this not Lix | Installing Lix?
        • [minion] it would be nice in our install guides to have lix stuff
        • [dfh] “migration into the new ecosystem” type page
          • [minion] ahhh, so almost what the getting started guide is currently
          • [minion] maybe we need to have “migration guide” and “install guide” separate?
  • Project and code standards
    • [minion] Maybe we shouldn’t be making orgwide decisions?
    • [dfh] we can at least decide this for the wiki/docs repos
      • [minion] so nixfmt-rfc-style for templates?
        • [dfh] how about treefmt, I might have some working flake code for this already
          • dfh to find this flake code
        • [minion] treefmt sounds good
    • minion to bring up global project standards with COMSTEER
  • Possible URL change
    • Jitsi Meet will avoid a room length warning
    • Should we selfhost?
      • Opentalk?
        • [dfh] Has some nice moderation stuff, like showing the order people raise their hands in
        • [dfh] Jitsi is a mess to host, opentalk should be a different pain if we decide to host
        • [dfh] Interested in moving COMSEC to something self-hosted…
  • Any other business
    • Wikijs needs js
      • coded/minion Finish fixing sidebar navigation pane. Get it up by the end of today
      • [dfh] look into “breadcrumbs” style sidebar where we can, e.g., go up multiple levels
        • [minion] could we also have something like a sitemap page?
        • [minion] let’s get a minimal version up before doing the other ideas…
      • [dfh] Idea: Browser-side search function (JS based) NLnet; Search NLnet

Decisions

  • Ping translators on the forum about how to be reminded about updating translations
  • Move up project and code standards to steering committee
  • Use treefmt
  • Talk with infra about hosting our own video call service

Standing reminders

  • Next meeting will be at the same time next week!
4 Likes

Found the code, turned out it was very pretty due to the use of the divnix/std framework which comes with some integrations between tools.

Not sure if we want to adopt this, I’ll just share my devshell config with a bunch of tools below as an example

{
  inputs,
  cell,
}: let
  pkgs = inputs.nixos.legacyPackages;
in {
  # conform is used to check for coonsistent commit messages. The goal is to
  # enforce meaningful commit documentation and practice the 'conventional commits'
  # standard, which in turn simplifies release processes and enables an
  # automated SemVer process.
  # See
  # - https://www.conventionalcommits.org/en/
  # - http://semver.org/
  conform = {
    data = {
      # std provides a conform integration which extracts the name of all
      # cells and makes them available to conform as scopes.
      inherit (inputs) cells;

      commit = {
        header = {
          length = 89;

          # The commit header is not a full sentence, hence it should not be
          # terminated with the dot character.
          invalidLastCharacters = ".";
        };

        # Require a commit body message, forcing this is elemental to foster a
        # culture of detailed commit descriptions.
        body = {required = true;};
        conventional = {
          types = [
            "build"
            "chore"
            "ci"
            "docs"
            "feat"
            "fix"
            "perf"
            "refactor"
            "style"
            "test"
          ];
          scopes = ["flake" "std"];
        };
      };
    };
  };

  # Consistent file formatting for all editors.
  # See https://editorconfig.org for configuration options.
  editorconfig = {
    # Place the files as copies into the checked out repo rather than symlinking
    # them from the nix store.
    hook.mode = "copy";

    # This attrset is based on stds default editorconfig located in
    # 'inputs.std.data.configs.editorconfig'.
    data = {
      # This is the top-most EditorConfig file
      root = true;

      # Rules applied to all files
      "*" = {
        # Unix style newlines for all files, always ending file with 'lf'
        # (instead of mid-line).
        end_of_line = "lf";
        insert_final_newline = true;

        # Set UTF-8 as default.#
        # This might not work with every filetype, it's OK to make this more
        # specific, but at least '*.nix'
        charset = "utf-8";

        # Trailing white-spaces happen easily and easily make for false git
        # changes. Since nix hashes all input files these type of accidental
        # changes are not really helpful -- let's trim them.
        trim_trailing_whitespace = true;

        # Indentation is always 2 whitespaces, tabs are considered evil.
        indent_style = "space";
        indent_size = 2;
      };

      # diffs and patches have their own format, depending on the tool that
      # crated them. So no messing with any formatting here
      "*.{diff,patch}" = {
        end_of_line = "unset";
        insert_final_newline = "unset";
        trim_trailing_whitespace = "unset";
        indent_size = "unset";
      };

      # Markdown rules are different than most code styles, automating correction
      # can introduce errors, hence they are disabled
      "*.md" = {
        max_line_length = "off";
        trim_trailing_whitespace = false;
      };

      # Any license files are just considered blobs of data, never re-format them
      # in any way.
      "{LICENSES/**,LICENSE}" = {
        end_of_line = "unset";
        insert_final_newline = "unset";
        trim_trailing_whitespace = "unset";
        charset = "unset";
        indent_style = "unset";
        indent_size = "unset";
      };
    };
  };
      # The std framework comes with a nice default configuration that has been
      # used as a base.
      # See https://github.com/divnix/std/blob/main/src/data/configs/treefmt.nix
      formatter = {
        # Default formatter for nix code
        nix = {
          command = "alejandra";
          includes = ["*.nix"];
          options = [
            # Check the formatting, but do not override files.
            #"--check"
          ];
        };
        # Deadnix tests nix code for unused variables/ expressions.
        deadnix = {
          command = "deadnix";
          includes = ["*.nix"];
          options = [
            # Don't edit files magically, but fail with errors. We want devs
            # to learn their trade properly ;-)
            "--fail"

            # Required to correctly parse std/ hive cell function signature,
            # because both require this fixed function signature, even if the
            # variables are not used.
            "--no-lambda-pattern-names"
          ];
        };

        # Prettier is capable of correctly formatting many different formats.
        prettier = {
          command = "prettier";
          options = [
            "--plugin"
            "${pkgs.nodePackages.prettier-plugin-toml}/lib/node_modules/prettier-plugin-toml/lib/api.js"
            "--check"
          ];
          includes = [
            "*.css"
            "*.html"
            "*.js"
            "*.json"
            "*.jsx"
            "*.md"
            "*.mdx"
            "*.scss"
            "*.ts"
            "*.yaml"
            "*.toml"
          ];
        };

        # Format shell scripts.
        shfmt = {
          command = "shfmt";
          includes = ["*.sh"];
          options = [
            # Number of spaces to use for indentation (instead of tabs)
            "--indent"
            "2"

            # Simplify the code - not sure what this does
            "--simplify"

            # Error out with a diff when recommended formatting differs
            "--diff"
          ];
        };

        # Lint shell scripts
        shellcheck = {
          command = "shellcheck";
          includes = ["*.sh"];
        };
      };
    };
  };
}

The std framework does quite some of the heavy lifting for the tool integrations and ease of use. I personally like it, but not sure if this would be applicable for the wiki, the framework has a strong DevOps focus.

2 Likes

Was this in Matrix? I haven’t experienced that before :thinking:

(Unsure where to put this, so I’ll put it here)

Re:

“this is outdated” message on old translated pages

I’ve taken a stab at implementing this at feat(i18n): display banner for outdated translations by liketechnik · Pull Request #22 · auxolotl/website · GitHub

I would appreciate help regarding styling and the mentioned error (in the linked PR) when building for CI though.

1 Like

no, we were previously using Jitsi with AuxDocs and we will move to AuxSigDocs from next week. This is to avoid the “this room name is insecure” warning

Thanks, @coded let’s take a look at this, I think all that’s left to do here is to solve some typescript issues and give some tailwind help … and hopefully that should be fairly straightforward :slight_smile:

I’d like to get this feature in ASAP

A post was split to a new topic: Relating nix commands to existing concepts

Thanks @dfh! You seem to have some strange

L.so.1: cannot open shared object file: No such file or directory

errors in the middle there, but I get the gist

re std: I have previously looked at it when contributing to projects such as frappix and found it pretty hard to read as a new user. It went quite far into its plant theming to the point where I struggled to follow what was happening (cells growOn soil layers…). It reminds me of homebrew. I also struggled with the overloading of ‘std’ as a name.

If you can motivate it well enough and we can document what it’s doing in a way that is understandable, I’m not completely opposed to it. If not, we should avoid using it.

2 Likes

Thx - fixed. No idea how that made into my c&p buffer…

Since it does quite some heavy lifting the default usage is quite different to the nix module system. Or most other libraries… I came to appreciate the heavy lifting and the aspect of blockTypes though because it’s a way I seem to compartmentalize things naturally.

HAHAHAHA very true… This took me quite some time to untangle too. It also seems it got a bit better recently.

IMO that’s always doable :wink:

I look at it a different way:

Would a devops like approach that yields results as described in 'why std` be beneficial when compared to the effort of learning & documenting the framework?

If the comparison does not feel positive, we should not use std.

3 Likes

Hey, I’ve just submitted a review that addresses both of your concerns.

Hadn’t checked Discourse before seeing the PR so I had no idea this came up as a result of the meeting, which is great!