dsfx/docs/internals/commits.md

# 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.