docs: update install, contrib, and usage documentationI6f4b5f5ca73780cecf66a553cce80aa3f75df2ce

This change refactors documentation, especially //:README.md,
//:CONTRIBUTING.md, and centralized most of the rest of the contributing
and usage documentation into `//doc`.

Documentation changes focus on cleaning up erroneous language,
reformatting, and restructuring docs in order to reduce visual noise -
the goals are to enable users and contributors to find what they're looking
for much more quickly, reduce (sometimes erroneous) duplication, and
present a structured approach for where to put docs.

Additionally:

- Added CI pipeline badge for the `trunk` workflow in `//:README.md`
- Converted embedded emoji characters to GitHub's emoji syntax
- Moved most sections with image and installation instructions into
  `<details>` elements
- Replaced references to gitter with matrix
- Introduced `treefmt-nix` to `devShells.default` in the flake, and all
  non-generated documentation was formatted with `nix fmt` (running
  `mdformat` under the hood)
- Regenerated //doc/md and //doc/man and refactored inline docs from various
  pages that were iterating out command line details so that they simply
  point to //doc/md instead
- Rewrote contributing docs to focus on using `nix`, to ensure that the
  development shell is used. This enforces consistency across different
  platforms with the revision and configuration of each tool we use, and
  simplifies the onboarding story for contributors -- they only need to
  install and configure nix (and optionally direnv). A dev container
  will be provided in the future [0] as an alternative for users on
  Windows (who can use WSL) or want to avoid installing `nix`.

[0]: https://github.com/git-bug/git-bug/issues/1364

Closes: #1212 #1276 #1330 #1357
Change-Id: I6f4b5f5ca73780cecf66a553cce80aa3f75df2ce

1 files changed, 151 insertions, 0 deletions

diff --git a/doc/feature-matrix.md b/doc/feature-matrix.md
new file mode 100644
index 00000000..18e37c18
--- /dev/null
+++ b/doc/feature-matrix.md
@@ -0,0 +1,151 @@
+# User facing capabilities
+
+This document tries to give an overview of what is currently supported, and by
+extension where effort can be focused to bring feature completion and parity.
+
+As git-bug is a free software project, accept and rely on contributor, those
+feature matrices kinda define a roadmap, in the sense that anything mentioned
+below is a planned feature and can be worked on. This does not mean that a
+feature not mentioned here should not be considered, just maybe check the issue
+tracker and come talk about it.
+
+This document however does not show all the untold work required to support
+those user-facing capabilities. There has been a ton of work behind the scene
+and more will be required over time.
+
+✅: working 🟠: partial implementation ❌: not working
+
+## Other goals
+
+Some goals don't really fit below, so I'll mention them here:
+
+- have the webUI accept external OAuth (Github, ...) and act as a public portal
+  where user outside the project can browse and interact with the project
+- project configuration (valid labels, ...)
+- commit signature to fully authenticate user's interaction
+- interface with the system keyring, to distribute and expose known public keys
+  and allow checking signed commit in normal git workflow
+- privileged roles (admin, ...) and enforcing the corresponding rules
+- package the webui as a desktop app
+
+Additionally, some other are captured as
+[Github issues](https://github.com/git-bug/git-bug/issues) or
+[Discussions](https://github.com/git-bug/git-bug/discussions).
+
+## Entities
+
+The most high level overview of what kind of entities are supported and where.
+
+|                | Core | CLI | TermUI | WebUI |
+| -------------- | :--: | :-: | :----: | :---: |
+| Identities     |  ✅  | ✅  |   ✅   |  ✅   |
+| Bug            |  ✅  | ✅  |   ✅   |  ✅   |
+| Board          |  🟠  | 🟠  |   ❌   |  ❌   |
+| Pull-request   |  ❌  | ❌  |   ❌   |  ❌   |
+| Project Config |  ❌  | ❌  |   ❌   |  ❌   |
+
+More specific features across the board.
+
+|                    | Core | CLI | TermUI | WebUI |
+| ------------------ | :--: | :-: | :----: | :---: |
+| Media embedding    |  🟠  | ❌  |   ❌   |  ❌   |
+| Fast indexing      |  ✅  | ✅  |   ✅   |  ✅   |
+| Markdown rendering | N/A  | ❌  |   ❌   |  ✅   |
+
+#### Identities
+
+|                         | Core | CLI | TermUI | WebUI |
+| ----------------------- | :--: | :-: | :----: | :---: |
+| Public keys             |  🟠  | ❌  |   ❌   |  ❌   |
+| Private keys management |  🟠  | ❌  |   ❌   |  ❌   |
+| Identity edition        |  ✅  | ✅  |   ❌   |  ❌   |
+| Identity adoption       |  ✅  | ✅  |   ❌   |  ❌   |
+| Identity protection     |  🟠  | ❌  |   ❌   |  ❌   |
+
+#### Bugs
+
+|                   | Core | CLI | TermUI | WebUI |
+| ----------------- | :--: | :-: | :----: | :---: |
+| Comments          |  ✅  | ✅  |   ✅   |  ✅   |
+| Comments edition  |  ✅  | ✅  |   ✅   |  ✅   |
+| Comments deletion |  ✅  | ❌  |   ❌   |  ❌   |
+| Labels            |  ✅  | ✅  |   ✅   |  ✅   |
+| Status            |  ✅  | ✅  |   ✅   |  ✅   |
+| Title edition     |  ✅  | ✅  |   ✅   |  ✅   |
+| Assignee          |  ❌  | ❌  |   ❌   |  ❌   |
+| Milestone         |  ❌  | ❌  |   ❌   |  ❌   |
+
+## Bridges
+
+### Importers
+
+General capabilities of importers:
+
+|                                                 | Github | Gitlab | Jira | Launchpad |
+| ----------------------------------------------- | :----: | :----: | :--: | :-------: |
+| **incremental**<br/>(can import more than once) |   ✅   |   ✅   |  ✅  |    ❌     |
+| **with resume**<br/>(download only new data)    |   ✅   |   ✅   |  ✅  |    ❌     |
+| **media/files**                                 |   ❌   |   ❌   |  ❌  |    ❌     |
+| **automated test suite**                        |   ✅   |   ✅   |  ❌  |    ❌     |
+
+Identity support:
+
+|                   | Github | Gitlab | Jira | Launchpad |
+| ----------------- | :----: | :----: | :--: | :-------: |
+| **identities**    |   ✅   |   ✅   |  ✅  |    ✅     |
+| identities update |   ❌   |   ❌   |  ❌  |    ❌     |
+| public keys       |   ❌   |   ❌   |  ❌  |    ❌     |
+
+Bug support:
+
+|                  | Github | Gitlab | Jira | Launchpad |
+| ---------------- | :----: | :----: | :--: | :-------: |
+| **bug**          |   ✅   |   ✅   |  ✅  |    ✅     |
+| comments         |   ✅   |   ✅   |  ✅  |    ✅     |
+| comment editions |   ✅   |   ❌   |  ✅  |    ❌     |
+| labels           |   ✅   |   ✅   |  ✅  |    ❌     |
+| status           |   ✅   |   ✅   |  ✅  |    ❌     |
+| title edition    |   ✅   |   ✅   |  ✅  |    ❌     |
+| Assignee         |   ❌   |   ❌   |  ❌  |    ❌     |
+| Milestone        |   ❌   |   ❌   |  ❌  |    ❌     |
+
+Board support:
+
+|           | Github | Gitlab | Jira | Launchpad |
+| --------- | :----: | :----: | :--: | :-------: |
+| **board** |   ❌   |   ❌   |  ❌  |    ❌     |
+
+### Exporters
+
+**General capabilities of exporters**:
+
+|                                                 | Github | Gitlab | Jira |
+| ----------------------------------------------- | :----: | :----: | :--: |
+| **incremental**<br/>(can export more than once) |   ✅   |   ✅   |  ✅  |
+| **with resume**<br/>(upload only new data)      |   ✅   |   ✅   |  ✅  |
+| **automated test suite**                        |   ✅   |   ✅   |  ❌  |
+
+**Identity support**:
+
+|                   | Github | Gitlab | Jira |
+| ----------------- | :----: | :----: | :--: |
+| **identities**    |   ✅   |   ✅   |  ✅  |
+| identities update |   ❌   |   ❌   |  ❌  |
+
+Note: as the target bug tracker require accounts and credentials, there is only
+so much that an exporter can do about identities. A bridge should be able to
+load and use credentials for multiple remote account, but when they are not
+available, the corresponding changes can't be replicated.
+
+**Bug support**:
+
+|                  | Github | Gitlab | Jira |
+| ---------------- | :----: | :----: | :--: |
+| **bugs**         |   ✅   |   ✅   |  ✅  |
+| comments         |   ✅   |   ✅   |  ✅  |
+| comment editions |   ✅   |   ✅   |  ✅  |
+| labels           |   ✅   |   ✅   |  ✅  |
+| status           |   ✅   |   ✅   |  ✅  |
+| title edition    |   ✅   |   ✅   |  ✅  |
+| Assignee         |   ❌   |   ❌   |  ❌  |
+| Milestone        |   ❌   |   ❌   |  ❌  |