Contributing

How to contribute to Project N.O.M.A.D. — guidelines, workflow, commit format, and release notes process.

Contributions are welcome and appreciated. Please read this page fully before getting started — it will save you and the maintainers time.

Acceptance of contributions is not guaranteed. All pull requests are evaluated based on quality, relevance, and alignment with the project’s goals. The maintainers reserve the right to accept, deny, or modify any pull request at their sole discretion.

Before you start

Open an issue first. Before writing any code, open an issue to discuss your proposed change. This avoids duplicate work and ensures your contribution fits the project’s direction.

When opening an issue:

• Use a clear, descriptive title
• Describe the problem you are solving or the feature you want to add
• If it is a bug, include steps to reproduce it and details about your environment
• Redact any personal or sensitive information in logs and configs

Contribution workflow

1. Fork the repository

   Click Fork at the top right of the GitHub repository to create a copy under your account.

   Then clone your fork and add the upstream remote:

   git clone https://github.com/YOUR_USERNAME/project-nomad.git
   cd project-nomad
   git remote add upstream https://github.com/Crosstalk-Solutions/project-nomad.git
   
2. Sync with upstream

   Before starting any new work, sync your fork with the latest upstream changes. Rebase is preferred over merge to keep a clean, linear history:

   git fetch upstream
   git checkout main
   git rebase upstream/main
   
3. Create a feature branch

   Create a new branch with a descriptive name that reflects the purpose of your changes:

   git checkout -b fix/issue-123
   # or
   git checkout -b feature/add-new-tool
   
4. Make your changes

   Implement your changes. Follow the existing code style and conventions. Test your changes locally against a running N.O.M.A.D. instance before submitting.

5. Add release notes

   If your changes include anything user-facing, add a summary to the ## Unreleased section at the top of admin/docs/release-notes.md. See Release Notes format below.

6. Commit your changes

   Commit using the Conventional Commits format. See the format description below.

7. Submit a pull request

   Push your branch to your fork and open a pull request against the main branch:

   git push origin your-branch-name
   

   In the PR description:

   • Summarize what your changes do and why
   • Reference the related issue (e.g., Closes #123)
   • Note any relevant testing steps or environment details

   Be responsive to feedback. Pull requests with no activity for an extended period may be closed.

Conventional commits

This project uses Conventional Commits. All commit messages must follow this format:

<type>(<scope>): <description>

Type	When to use
feat	A new user-facing feature
fix	A bug fix
docs	Documentation changes only
refactor	Code change that is not a fix or feature
chore	Build process, dependency updates, tooling
test	Adding or updating tests

The scope is optional but encouraged — use it to indicate the area of the codebase affected (e.g., api, ui, maps).

Examples:

feat(ui): add dark mode toggle to Command Center
fix(api): resolve container status not updating after restart
docs: update hardware requirements in README
chore(deps): bump docker-compose to v2.24

Release notes format

Human-readable release notes live in admin/docs/release-notes.md and are displayed in the Command Center UI.

When your changes include anything user-facing, add an entry to the ## Unreleased section at the top of that file:

## Unreleased

### Features
- **Maps**: Added support for downloading South America regional maps

### Bug Fixes
- **AI Chat**: Fixed document upload failing on filenames with special characters

Use the format - **Area**: Description to stay consistent with existing entries.

Headings to use:

• Features — new user-facing capabilities
• Bug Fixes — corrections to existing behavior
• Improvements — enhancements, refactors, docs, or dependency updates

When a release is triggered, CI automatically stamps the version and date, commits the update, and publishes the content to the GitHub release. You do not need to do this manually.

Versioning

This project uses Semantic Versioning. Versions are managed in the root package.json and updated automatically by semantic-release. The project-nomad Docker image uses this version. The admin/package.json version stays at 0.0.0 and should not be changed manually.

Code of conduct

Please read the full Code of Conduct before contributing. In short: be respectful and considerate in all interactions with maintainers and other contributors. Disrespectful or abusive behavior will not be tolerated.