Replace mdox with pre-commit and various improvement

Author: acolombier

.github/.mdox.validator.yaml

@@ -0,0 +1,27 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+    - uses: pre-commit/action@v3.0.1
+    - name: "Generate patch file"
+      if: failure()
+      run: |
+        git diff-index -p HEAD > "${PATCH_FILE}"
+        [ -s "${PATCH_FILE}" ] && echo "UPLOAD_PATCH_FILE=${PATCH_FILE}" >> "${GITHUB_ENV}"
+      env:
+        PATCH_FILE: pre-commit.patch
+
+    - name: "Upload patch artifact"
+      if: failure() && env.UPLOAD_PATCH_FILE != null
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ env.UPLOAD_PATCH_FILE }}
+        path: ${{ env.UPLOAD_PATCH_FILE }}

.github/workflows/pre-commit.yml

@@ -0,0 +1,12 @@
+config:
+  fix: true
+
+# MD013/line-length - Line length
+MD013:
+  line_length: 120
+  tables: false
+  ignore_code_blocks: true
+
+MD033:
+  allowed_elements:
+    - GH # This isn't an element but is detected as such in the template

.github/workflows/proposals.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-symlinks
+      - id: end-of-file-fixer
+      - id: check-byte-order-marker
+      - id: check-case-conflict
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+  - repo: https://github.com/trussworks/pre-commit-hooks
+    rev: v1.1.1
+    hooks:
+      - id: markdown-toc
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.13.0
+    hooks:
+    - id: markdownlint-cli2
+      entry: markdownlint-cli2
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        name: codespell
+        description: Checks for common misspellings in text files.
+        entry: codespell -w

.gitignore

@@ -7,7 +7,8 @@ See [README](README.md) for details.
 ## Your Proposal Title
 
 * **Owners:**
-  * `<@author: single champion for the moment of writing. No need to add contributors all will be visible in commit or comments history on GitHub.>`
+  * `<@author: single champion for the moment of writing. No need to add contributors
+    all will be visible in commit or comments history on GitHub.>`
 
 * **Implementation Status:** `Not implemented / Partially implemented / Implemented`
 
@@ -17,21 +18,27 @@ See [README](README.md) for details.
 * **Other docs or links:**
   * `<Links…>`
 
-> TL;DR: Give here a short summary of what this document is proposing and what components it is touching. Outline rough idea of proposer's view on proposed changes.
+> TL;DR: Give here a short summary of what this document is proposing and what components it is touching. Outline rough
+> idea of proposer's view on proposed changes.
 >
 > *For example: This design doc is proposing a consistent design template for “example.com” organization.*
 
 ## Why
 
 Put here a motivation behind the change proposed by this design document, give context.
 
-*For example: It’s important to clearly explain the reasons behind certain design decisions in order to have a consensus between team members, as well as external stakeholders. Such a design document can also be used as a reference and knowledge-sharing purposes. That’s why we are proposing a consistent style of the design document that will be used for future designs.*
+*For example: It’s important to clearly explain the reasons behind certain design decisions in order to have a consensus
+between team members, as well as external stakeholders. Such a design document can also be used as a reference and
+knowledge-sharing purposes. That’s why we are proposing a consistent style of the design document that will be used for
+future designs.*
 
 ### Pitfalls of the current solution
 
 What specific problems are we hitting with the current solution? Why it’s not enough?
 
-*For example, We were missing a consistent design doc template, so each team/person was creating their own. Because of inconsistencies, those documents were harder to understand, and it was easy to miss important sections. This was causing certain engineering time to be wasted.*
+*For example, We were missing a consistent design doc template, so each team/person was creating their own. Because of
+inconsistencies, those documents were harder to understand, and it was easy to miss important sections. This was
+causing certain engineering time to be wasted.*
 
 ## Goals
 
@@ -61,7 +68,8 @@ Explain the full overview of the proposed solution. Some guidelines:
 
 ## Alternatives
 
-The section stating potential alternatives. Highlight the objections reader should have towards your proposal as they read it. Tell them why you still think you should take this path [[ref](https://twitter.com/whereistanya/status/1353853753439490049)]
+The section stating potential alternatives. Highlight the objections reader should have towards your proposal as they
+read it. Tell them why you still think you should take this path.
 
 1. This is why not solution Z...
 

.markdownlint.yaml

@@ -1,86 +1,3 @@
 # Mixxx Code of Conduct
 
-The Mixxx team is committed to preserving and fostering a
-diverse, welcoming community. Below is our community code of conduct, which
-applies to our repos and organizations, mailing lists, forums, IRC channels,
-blog content, and any
-other Mixxx-supported communication group, as well as any private
-communication initiated in the context of these spaces.
-
-Simply put, community discussions should be
-
-* respectful and kind;
-* about Mixxx;
-* about features and code, not the individuals involved.
-
-## Be respectful and constructive
-
-Treat everyone with respect. Build on each other's ideas. Each of us has the
-right to enjoy our experience and participate without fear of harassment,
-discrimination, or condescension, whether blatant or subtle. Remember that
-Mixxx is a geographically distributed team and that you may not be
-communicating with someone in their primary language. We all get frustrated
-when working on hard problems, but we cannot allow that frustration to turn
-into personal attacks.
-
-## Speak up if you see or hear something
-
-You are empowered to politely engage when you feel that you or others are
-disrespected. The person making you feel uncomfortable may not be aware of what
-they are doing - politely bringing their behavior to their attention is
-encouraged.
-
-If you are uncomfortable speaking up, or feel that your concerns are not being
-duly considered, you can email community@mixxx.org to request involvement
-from a community manager. You may also email any of the community managers
-directly. All concerns shared with community managers will be kept
-confidential. In cases where a public response is deemed necessary, the
-identities of victims and reporters will remain confidential unless those
-individuals instruct us otherwise.
-
-While all reports will be taken seriously, the Mixxx community managers may
-not act on complaints that they feel are not violations of this code of
-conduct.
-
-## No Tolerance for Harassment
-
-We will not tolerate harassment of any kind, including but not limited to:
-
-* Harassing comments
-* Intimidation
-* Encouraging a person to engage in self-harm.
-* Sustained disruption or derailing of threads, channels, lists, etc.
-* Offensive or violent comments, jokes or otherwise
-* Inappropriate sexual content
-* Unwelcome sexual or otherwise aggressive attention
-* Continued one-on-one communication after requests to cease
-* Distribution or threat of distribution of people's personally identifying
-  information, AKA “doxing”
-
-## Consequences for failing to comply with this policy
-
-Consequences for failing to comply with this policy may include, at the sole
-discretion of the Mixxx community managers:
-
-* a request for an apology;
-* a private or public warning or reprimand;
-* a temporary ban from the mailing list, blog, Mixxx repository or
-  organization, or other Mixxx-supported communication group, including
-  loss of committer status;
-* a permanent ban from any of the above, or from all current and future
-  Mixxx-supported communities, including loss of
-  committer status.
-
-Participants warned to stop any harassing behavior are expected to comply
-immediately; failure to do so will result in an escalation of consequences.
-
-## Acknowledgements
-
-This Code of Conduct is based on the Chromium Code of Conduct, which credits
-the Geek Feminism Code of Conduct, the Django Code of Conduct and the Geek
-Feminism Wiki "Effective codes of conduct" guide.
-
-## License
-
-This Code of Conduct is available for reuse under the Creative Commons Zero
-(CC0) license.
+Please see the Code of Conduct in [the main Mixxx repo](https://github.com/mixxxdj/mixxx/blob/main/CODE_OF_CONDUCT.md)

.pre-commit-config.yaml

@@ -5,37 +5,58 @@ reviewing, discovering, and working on the design documents. It is also a record
 
 ## Current Proposals
 
-* The [open PRs with the `proposal` label](https://github.com/mixxxdj/proposals/pulls?q=is%3Aopen+is%3Apr+label%3Aproposal) show all the pending proposals.
-* The [proposals directory](./proposals) shows all the accepted proposals. See the “Implementation Status” for details on the implementation.
-* The [PRs with the `proposal` label that are closed without merging](https://github.com/mixxxdj/proposals/pulls?q=is%3Apr+label%3Aproposal+is%3Aclosed+is%3Aunmerged) show all the rejected proposals.
+* The
+  [open PRs with the `proposal` label](https://github.com/acolombier/mixxx-proposals/pulls?q=is%3Aopen+is%3Apr+label%3Aproposal)
+  show all the pending proposals.
+* The [proposals directory](./proposals) shows all the accepted proposals. See the “Implementation Status” for details
+  on the implementation.
+* The
+  [PRs with the `proposal` label that are closed without merging](https://github.com/acolombier/mixxx-proposals/pulls?q=is%3Apr+label%3Aproposal+is%3Aclosed+is%3Aunmerged)
+  show all the rejected proposals.
 
 ## What’s a Design Document?
 
-It’s essential to clearly explain the reasons behind certain design decisions to have a community consensus. This is especially
-important in Mixxx, where every decision might have a significant impact given the high adoption and stability of the software and standards we work on.
+It’s essential to clearly explain the reasons behind certain design decisions to have a community consensus. This is
+especially important in Mixxx, where every decision might have a significant impact given the high adoption and
+stability of the software and standards we work on.
 
 In our world, no decision is perfect, so having a design document explaining our trade-offs is essential.
 Such a document can also be used later as a reference and for knowledge-sharing purposes.
 
 Design documents do not always reflect what has been (or will be) implemented. Implementation details
-might have changed since a feature was merged. Design docs are not considered documentation and can not define a standard.
+might have changed since a feature was merged. Design docs are not considered documentation and can not define a
+standard.
 Instead, it should explain the motivation, scope, decisions, and alternatives considered.
 
+A design document shall describe the use-cases the proposal will implement and also the use-cases that are explicitly
+not included.
+
+It may also contain requirements and acceptance criteria of a derived Pull Request. This avoid feature creep and adjust
+the expectations during a review.
+
 ## Proposal Process
 
 Don’t get scared to propose ideas! It’s amazing to innovate in the open and get feedback on ideas.
 
 The process of proposing a change via a design document is the following:
 
-1. Fork `github.com/mixxxdj/proposals`.
-2. Create a GitHub Pull Request with a design document in markdown format to the [proposals directory](./proposals). Make sure to use the [template](0000-00-00_template.md) as the guide for what sections should be present in the document. Put the creation date (the day you started preparing this design document) as the prefix and some unique name as the suffix in the file name. Once the PR is proposed, a maintainer will assign a `proposal` label.
-3. An automatic formatter is enabled in the repository. Use `make` locally to trigger the formatting of all markdown documents (requires a working Go environment). Use `make check` to check all links (will be done by the CI pipeline, too).
-4. After a sufficient amount of discussion, the Mixxx team will try to reach a consensus of accepting or rejecting the proposal. In the former case, the PR gets merged. In the latter case, the PR gets closed with meaningful reasons why the proposal was rejected.
+1. Fork `github.com/acolombier/mixxx-proposals`.
+2. Create a GitHub Pull Request with a design document in markdown format to the [proposals directory](./proposals).
+   Make sure to use the [template](0000-00-00_template.md) as the guide for what sections should be present in the
+   document. Put the creation date (the day you started preparing this design document) as the prefix and some unique
+   name as the suffix in the file name. Once the PR is proposed, a maintainer will assign a `proposal` label.
+3. An automatic formatter is enabled in the repository. Use `pre-commit` locally to trigger the formatting of all
+   markdown documents (requires a working `pre-commit` installation).
+4. After a sufficient amount of discussion, the Mixxx team will try to reach a consensus of accepting or rejecting the
+   proposal. In the former case, the PR gets merged. In the latter case, the PR gets closed with meaningful reasons why
+   the proposal was rejected.
    1. To merge the PR, we need approval (consensus) from the maintainers of the related component(s).
-   2. Optionally: Find a sponsor among the Mixxx maintainers to get momentum on a change.
+   2. Optionally: Find a sponsor among the Mixxx maintainers to get momentum on a change. You may use
+      [Zulip](https://mixxx.zulipchat.com/) to do that.
 
-Once the PR gets merged, the design document can change, but it requires (less strict, but still) a PR with review and merge by a maintainer.
+Once the PR gets merged, the design document can change, but it requires (less strict, but still) a PR with review and
+merge by a maintainer.
 
 ## Credits
 
-This proposal process was largely inspired by the [Prometheus Proposal Process](https://github.com/prometheus/proposals)
+This proposal process was largely inspired by the [Prometheus Proposal Process](https://github.com/prometheus/proposals)