mirror of
https://git.numenor-labs.us/dsfx.git
synced 2025-04-29 16:20:34 +00:00
155 lines
4.6 KiB
Markdown
155 lines
4.6 KiB
Markdown
# 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.
|