docs: add CONTRIBUTING.md file

[qlrd]

What is this PR for?

CONTRIBUTING.md is a important file that guides new developers through the standards built by krux team through years. This isn't a monad and could be changed at time to time.

Changes made to:

• Code
• Tests
• Docs
• CHANGELOG

Did you build the code and tested on device?

• Yes, build and tested on

What is the purpose of this pull request?

• Bug fix
• New feature
• Docs update
• Other

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.30%. Comparing base (9ef5803) to head (db7641d).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #816   +/-   ##
========================================
  Coverage    97.30%   97.30%           
========================================
  Files           83       83           
  Lines        10798    10798           
========================================
  Hits         10507    10507           
  Misses         291      291           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[odudex]

Needs a few changes

[qlrd]

@odudex, thought if is worth to down or maintain 3.12, wdyt?

[odudex]

IMO the source of this information is pyproject.toml. No need to replicate (and maintain) it elsewhere. You can add a link to the file mentioning user can learn about all python dependencies there.
No need to lower the requirement version. This is a decision the would require testing anyway.
Let project.toml speak for itself

[qlrd]

Removed and added a #863 to address that, wdyt?

[odudex]

Please ensure everything CONTRIBUTING.md states is true now. Code style, what is enforced by CI, what's not. It must be coherent with project's current status.
If new requirements and tools will later be adopted, then CONTRIBUTING can be adjusted accordingly.

[odudex]

1. Python version is stated three different ways across the repo, and CONTRIBUTING adds a fourth conflict.

• CONTRIBUTING.md:119 says minimum is 3.12.0 and "enforced by our CI".
• pyproject.toml:32 requires python = "^3.12.3".
• .github/workflows/tests.yml actually runs CI on 3.11 for every job (lint, pylint, tests, coverage).
• The claim "enforced by our CI" is therefore false. CI doesn't enforce 3.12 at all.

2. Markdown linting is not enforced.

• CONTRIBUTING.md:215 says rules "are enforced by CI, both for python and markdown code" and lists markdown rules at line 278.
• No markdown linter exists in .github/workflows/, and no .markdownlint*/.pymarkdown* config is present. There's an in-flight branch ci/pymarkdownlnt, but it hasn't landed.

3. Conventional-commit types list is incomplete.

• CONTRIBUTING.md:130-142 lists 8 types.
• .github/workflows/conventional-commits.yml allows feat,fix,docs,style,refactor,test,i18n,ci,chore,git.
• i18n and git are missing from the doc despite being CI-allowed.

4. Fork instructions are wrong.
   • CONTRIBUTING.md:67 shows git clone git@github.com:selfcustody/krux.git under "Fork Repository". That clones upstream, not a fork. There's no instruction to actually fork via GitHub or add the upstream remote.
5. CONTRIBUTING.md:260, 263 uses instanceof(...) — that's JavaScript. Python is isinstance(...). The "good example" wouldn't run.
6. CONTRIBUTING.md:226-231 Python skeleton is indented 3 / 6 / 12 spaces — black (which the project uses) will rewrite to 4-space. Example contradicts the formatter that CI runs.

[qlrd]

The claim "enforced by our CI" is therefore false. CI doesn't enforce 3.12 at all.

Removed

CONTRIBUTING.md:260, 263 uses instanceof(...) — that's JavaScript. Python is isinstance(...). The "good example" wouldn't run.

Sorry, my fault

CONTRIBUTING.md:226-231 Python skeleton is indented 3 / 6 / 12 spaces — black (which the project uses) will rewrite to 4-space. Example contradicts the formatter that CI runs.

think was local markdown linter, txs

[odudex]

utACK 88e153f4

The overall structure (workflow → review →
conventions → testing → release) is the right shape. The following first
three instructions are blocking, the rest are nits.

Blocking

1. Broken link to SECURITY.md. The release section points contributors
   with security issues to ./SECURITY.md, but that file doesn't exist in
   the repo. Could we either add a stub SECURITY.md (even a short one
   pointing at a contact address or GitHub's security advisory flow) or
   change the link to wherever we actually want reports to go?

2. Fork / clone instructions are contradictory. The first block tells
   the contributor to fork and clone their fork; the "Stay update with the
   upstream" subsection then says to instead clone the upstream as origin
   and add the fork as a named remote. That's the opposite of the
   conventional setup and contradicts the step right above it. I'd suggest
   picking one approach — typically: clone your fork as origin, then
   git remote add upstream git@github.com:selfcustody/krux.git.

3. Workflow list is truncated. The numbered list reads:

   1. Fork Repository
   2. Create topic branch
   3. Commit patches
   

   The two steps that actually produce a contribution (push to fork, open
   PR, then address review) are missing. Also "the workflow is as follows:"
   appears twice back-to-back.

Non-blocking suggestions

4. git as a commit type. The doc claims Conventional Commits 1.0.0,
   then lists git with the description "used when changing some git
   stuffs". That isn't part of the spec and the description is hard to
   act on. Could we either drop it or define exactly what it covers
   (.gitignore, .gitattributes?) — though those would normally fit
   under chore.

5. CHANGELOG placement. The Added CONTRIBUTING.md guidelines line
   landed in ### Other Bug Fixes and Improvements. By the doc's own
   taxonomy that's a docs change, not a fix/improvement. Either a new
   ### Documentation subsection or just dropping the changelog entry
   (the commit itself is self-describing) would feel more consistent.

6. nACK definition is ambiguous. Line currently reads:

   Approach nACK: "I do (not) agree with the approach of this change"

   The (not) reads as a typo. nACK is unambiguously "I do not agree" —
   suggest dropping the parens.

7. Unreferenced footnote. [^1]: https://withblue.ink/...how-and-why-to-sign-git-commits.html
   sits at the bottom of the file but no [^1] is referenced anywhere in
   the body. Either link it from a paragraph (a short note on signing
   commits would be a natural spot) or remove it.

8. poetry run poe discoverability. "See more with poetry run poe"
   prints usage rather than the task list — poetry run poe --help (or
   pointing readers at the [tool.poe.tasks] block in pyproject.toml)
   is what we probably want here.

Changelog

We use CHANGELOG mostly to report firmware changes to users, sometimes simulator, but not project structure and development related changes.

Copy / typos

• Commit body: "a important file" → "an important file"; "isn't a
  monad" — I think the intended word is monolith (a monad is a
  category-theory construct; "not set in stone" is the meaning here).
• "Stay update with the upstream" → "Stay up to date with upstream".
• "as did in previously step" → "as in the previous step".
• "mostly addtion/fix" → "addition".
• The Python docstring example shows """Some awesome comment""" as a
  placeholder; a one-line realistic summary would teach more.
• The doc enforces 80 chars per line for markdown, but several lines in
  the file itself exceed that (e.g. the contributors-list line). Running
  the project's markdown linter against it would catch these.

Smaller structural notes

• The "Named branches" section is mostly about commit hygiene (atomic
  commits, no mixing formatting with code). Splitting into "Branch
  naming" and "Commit hygiene" would match the content.
• tACK / utACK are defined under both "Conceptual Review" and "Code
  Review". Defining them once and cross-referencing would shorten the
  section.
• The Code Review example's <diff> block is non-standard and won't
  render the way the prose implies — a fenced ```diff block would be
  cleaner.

What's good

The Conventional Commits list (with the git caveat) is concrete and
actionable, the ACK / nACK / tACK / utACK vocabulary borrowed from the
Bitcoin Core review culture fits this project's audience well, and
linking the poe lint / poe format tasks ties the doc to commands
people will actually run. Nice first cut overall — happy to help with
any of the above if useful.

[qlrd]

Addressed Blocking issues (and removed CHANGELOG change)

git as a commit type.

already addressed

Approach nACK: "I do (not) agree with the approach of this change"
The (not) reads as a typo. nACK is unambiguously "I do not agree" — suggest dropping the parens.

This is how is in Floresta

typically: clone your fork as origin, then
git remote add upstream git@github.com:selfcustody/krux.git.

I had problems with the submodules --init --recursive using upstream instead origin. AFAIK the git need it to be named as origin (if have another way, great). So i think i will put only the first.

I think we could open sub-issues for non-blocking and address them on follow-ups, sounds good?

[bitcoisas]

Strong cACK

After reading the full text and comments, just some nits/observations:

• CHANGELOG not mentioned: The PR template has a CHANGELOG checkbox,
  but the guide never tells contributors when they should update it.
  Worth adding a line under the Open PR section, IMO.
• Commit signing: @qlrd suggested commits should follow the same signing
  behaviour as release assets, but this seems unresolved. Worth settling
  before merge. Is signing a requirement, recommendation, or out of scope?

[bitcoisas]

stuff is uncountable in English

[odudex]

The commit from this PR was merged, with a follow up with fixes and more conciseness.