numenor-labs/dsfx
2
0
Fork 0
mirror of https://git.numenor-labs.us/dsfx.git synced 2025-04-29 16:20:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
dsfx/docs/internals/commits.md

4.6 KiB
Raw Blame History

Commit Strategy

The project utilizes convetional commits to standardize commit messages across the codebase. This document outlines the guidelines for writing commit messages that adhere to the Conventional Commits specification.

Commit Message Structure

Every commit message MUST follow this structure:

type(scope): subject

[body]

[footer]
  • The header (first line) must not exceed 100 characters.
  • The body (if provided) should explain the what and the why behind the change.
  • The footer is reserved for any breaking changes or referencing issues.

Allowed Commit Types

Use one of the following types to describe your commits:

  • feat: A new feature for the user.
  • fix: A bug fix.
  • docs: Documentation changes (in-code or external docs).
  • style: Changes that do not affect the code meaning (formatting, semicolons, white-space, etc.).
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • perf: A code change that improves performance.
  • test: Adding missing tests or correcting existing tests.
  • build: Changes affecting the build system or external dependencies.
  • ci: Changes to the Continuous Integration configuration files and scripts.
  • chore: Maintenance tasks (updating auxiliary tools or routines).
  • revert: Reverts a previous commit (use the prefix “Revert:” in the subject).

Allowed Scopes

Our project’s structure suggests a set of scopes that reflect the affected areas. When you add a scope, choose one that best describes where your change applies. Below are our recommended scopes:

Command-line Tools

  • cmd/dsfx – Core DSFX application commands.
  • cmd/dsfxctl – Client-side commands (for dsfxctl).
  • cmd/dsfxnode – Node or peer functionality.

Client & Peer

  • internal/client – Client functionality (dsfxctl).
  • internal/peer – Peer and node operations (dsfxnode).

Core Libraries (located in internal/lib)

  • assert – Assertion helpers.
  • buffer – Buffer utilities (length-prefixed buffers).
  • crypto
    • encryption – AEAD encryption and decryption routines.
    • identity – Ed25519 key generation, signing, and verification.
    • keyexchange – ECDH key exchange routines.
  • disk – File system abstractions.
  • frame – Network frame handling.
  • handshake – Handshake protocol implementation.
  • logging – Internal logging and context-based utilities.
  • network – Network addresses, connections, listener/dialer functionalities.
  • storage – Scoped storage interfaces.
  • system – System-level operations and environment access.

Simulation

  • internal/sim – In-memory file system and simulated system tools.

Tools

  • internal/tool – Auxiliary tools (e.g., benchmarks, key generators).

Documentation

  • docs – Documentation improvements or changes.

Note: When a commit affects multiple areas, pick the scope that best represents the overall change; you may also leave it empty.

Examples

Here are a few examples of acceptable commit messages:

  • Feature example:

    feat(client): add new file upload progress indicator

Introduces a visual progress indicator for file uploads in the dsfxctl client.

  • Bug fix example:

    fix(handshake): correct nonce handling in authentication message

Adjusts nonce extraction to fix a potential off-by-one error during handshake.

  • Documentation update example:

    docs: update internal documentation for conventional commits

Added a new internal doc explaining our Conventional Commits guidelines.

  • Refactor example:

    refactor(network): simplify dial and connection setup logic

Consolidated redundant code in network dialers for improved maintainability.

  • Performance improvement example:

    perf(disk): optimize file write performance in SimDisk

Reduced simulated disk latency by refining timeout computations.

Breaking Changes

If a commit introduces a backward-incompatible change, include a BREAKING CHANGE: token in the footer. For example:

feat(core): update authentication protocol

BREAKING CHANGE: The client handshake now requires additional parameters.

Conclusion

Adopting Conventional Commits is a step toward ensuring a clear revision history and facilitating automated changelog generation. Keep your commit messages short, descriptive, and consistent with these guidelines.

Place this document in your internal docs folder (e.g., /docs/internal/CONVENTIONAL_COMMITS.md) and use it as a reference for all contributors.