mfgames-project-setup-flake/README.md

# MfGames Project Setup Flake

_An opinionated setup for projects using Nix flakes._

According to Larry Wall, there are
[three virtues of a great coder](https://thethreevirtues.com/): laziness,
impatience, and hubris.

Over the years, the complexity of being a developer has only increased.
Fortunately (or unfortunately depending the mood), we have embraced laziness and
developed tools to help automate some of the more tedious tasks to ensure
everything is formatted correctly and properly recorded. This has resulted in
libraries such as:

- [EditorConfig](https://editorconfig.org/)
- [Conform](https://github.com/siderolabs/conform)
- [Lefthook](https://github.com/evilmartians/lefthook)
- [Prettier](https://prettier.io/)
- [Rustfmt](https://rust-lang.github.io/rustfmt/)
- [Treefmt](https://numtide.github.io/treefmt/)

In addition, we need to document policies that guide our projects:

- [Contributor Convenant](https://www.contributor-covenant.org/)
- [Developer Certificate of Origin](https://developercertificate.org/)

But, like the rest of the development world, all of these tools change and
evolve. New tools become useful to ensure formatting while others are taken over
by successors. Not to mention opinions and aesthetics change and what works
yesterday doesn't always look right today.

## Nix

This project is intended to be used with [Nix](https://nixos.wiki/wiki/Flakes)
flakes and can be used directly as an input.

```nix
{
  inputs.mfgames-project-setup.url = "git+https://src.mfgames.com/nixos-contrib/mfgames-project-setup-flake.git";
}
```

This flake provides a function in `mfgames-project-setup.lib.mkConfig` that
creates a shell hook and the various tools required to run those hooks (because
programs like `lefthook` assume that the program is in the `PATH`).

```nix
config = mfgames-project-setup.lib.mkConfig {
    inherit system pkgs;
    # Options go here.
};
```

Of course, this being Nix, there are many ways of creating a devShell. This is
one way of using the config inside the shell.

```nix
devShells = forEachSupportedSystem ({ system, pkgs }:
let
    config = inputs.mfgames-project-setup.lib.mkConfig {
        inherit system pkgs;
        conform.scopes = [ "cli" "website" ];
        rust.enable = false;
    };
in
{
    default = pkgs.mkShell {
        # Add in the required packages for the configuration.
        packages = [] ++ config.packages;

        # Add in the
        shellHook = ''
            ${config.shellHook}
        '';
    };
});
```

## Options

This is definately opinionated, mainly by the virtue that is primarily used by a
single developer. Internally, this uses
[Nixago](https://github.com/nix-community/nixago) (including a little hacking
for text files).

### conform.scopes

Controls which scope is allowed inside the
[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/).

Defaults to `[]`. An example would be `["cli" "infra"]`.

### contributorCovenant.enable

If set to true, then a `CODE_OF_CONDUCT.md` will be created using information
from `contributorCovenant.contact` for the contact information. If the contact
is missing, this will assert.

Defaults to `false`.

### contributorCovenant.contact

Set this to the value for the contact information inside the
`CODE_OF_CONDUCT.md` file. This can be an email or a website.

### copyright

The copyright statement to include, if needed. This should be in the format of
"<year>, <copyright holder>". The "Copyright" and any symbols will be included
if needed.

### creativeCommonsAttributionNonCommercialShareAlike.enable

If set to true, then write out a Creative Commons BY-NC-SA license file to
`creativeCommonsAttributionNonCommercialShareAlike.filename`.

### creativeCommonsAttributionNonCommercialShareAlike.filename

The name of the file to emit.

Defaults to `LICENSE.md`.

### creativeCommonsAttributionShareAlike.enable

If set to true, then write out a Creative Commons BY-SA license file to
`creativeCommonsAttributionShareAlike.filename`.

### creativeCommonsAttributionShareAlike.filename

The name of the file to emit.

Defaults to `LICENSE.md`.

### developerCertificateOfOrigin.enable

If set to true, then a `DCO.md` will be created using the boilerplate text from
https://developercertificate.org/.

Defaults to `false`.

### mit.enable

If set to true, then write out a MIT license file to `mit.filename`. This
requires `copyright` to be set because the resulting file will contain it.

### mit.filename

The name of the file to emit.

Defaults to `LICENSE.md`.

### prettier.proseWrap

Allows changing the proseWrap setting to one of the known values: `preserve`,
`always`, `never`.

Defaults to `preserve`.

### rust.enable

If set to true, then `rustfmt.toml` will be created.

Defaults to `false`.