Contributing

Repository setup

Before contributing, follow the Local Development guide to set up your environment.

---

Branching

• main — stable, deployable state. Direct commits to main are discouraged.
• Feature branches — use descriptive names: feat/requisition-email-notifications, fix/snipeit-sync-timeout.
• Documentation branches — prefix with docs/: docs/add-mobile-guide.

To verify: confirm the team's specific branching and PR conventions in the repository's own README.md or team communication channel, as these may not be documented yet.

---

Making changes

1. Create a branch from main.
2. Make your changes.
3. Run the stack locally and verify your changes manually (see Testing).
4. Commit with a clear message:

   feat: add equipment catalog search filter
   fix: handle null snipeit_asset_id in sync
   docs: update deployment checklist

5. Open a pull request targeting main.

---

Code review expectations

• All pull requests should include a brief description of what changed and why.
• Breaking changes to the API should update the API Reference.
• Database schema changes should update infra/db/init/schema.sql and Database.
• Deployment-relevant changes should update Deployment.

---

Adding or updating documentation

The documentation lives in deti-maker-lab.github.io/docs/.

Adding a new page

1. Create a .md file in the appropriate section directory.
2. Add Docusaurus front matter at the top:

   ---
   sidebar_position: <number>
   title: Page Title
   description: Short description shown in SEO and sidebar.
   ---

3. The page will appear in the sidebar automatically (autogenerated sidebar).

Adding a new section

1. Create a new directory under docs/.
2. Add a _category_.json file:

   {
     "label": "Section Name",
     "position": <number>,
     "link": {
       "type": "generated-index",
       "description": "Section description."
     }
   }

Keeping docs synchronized with /core

The source of truth for implementation details is always the code in /core. When making code changes:

• If a new API endpoint is added, update API Reference.
• If environment variables change, update Environment Configuration.
• If the database schema changes, update Database and Data Model.
• If the deployment process changes, update the relevant Deployment pages.

---

Docusaurus conventions

• Use front matter for every page (sidebar_position, title, description).
• Use admonitions for important callouts (:::info, :::warning, :::tip).
• Use Mermaid code blocks for diagrams (requires Mermaid support to be enabled in the Docusaurus config).
• Use relative links between docs pages.
• Use code blocks with language identifiers for syntax highlighting.

---

Building the docs site

cd deti-maker-lab.github.io
npm run build

Verify the build succeeds before merging documentation changes. Fix broken links reported by Docusaurus (onBrokenLinks: 'throw' is configured).