Contributing

verified

This guide should work for anyone joining the organization, including people without a technical background or repository access.

Help improve this guide

You do not need access to the code to contribute. Tell the team lead which page you were reading, what was confusing or missing, and what you expected to find. A screenshot or a suggested sentence is helpful, but not required.

If an application behaves differently from the guide, include its name and whether you were using staging or production. Do not send passwords or private account details. The team can check the information and arrange an update.

For maintainers: editing and validating the site

Run and validate

From this repository, using Node 24.19.0 as pinned in .nvmrc:

npm install
npm run dev

Before every commit:

npm run format
npm run build
npm run format:check

Inspect the production output with npm run preview.

Add or revise content

Edit Markdown under the repository root. Add approved pages to .vitepress/sidebar.ts in reading order. Keep the home page at index.md. New pages outside the first-release structure need a reason in the commit message.

Use one idea per short paragraph. Explain acronyms on each page where they first appear. Never use em dashes. Do not include secrets, server addresses expressed as IPs, credentials or seeded passwords. Use product names consistently and link public help instead of copying its tutorials.

Every technical claim needs a link to its source repository file. Use staging for sibling source links, main for lt-player and this site's own files. The reviewed source checkout may move; recheck the claim when editing. Put disagreements and missing information in Open questions, with a page and expected resolver.

Components and tables

The reusable components live in the theme.

• Status: place <Status value="verified" />, needs verification or gap immediately below the title. Use verified for code-backed behavior, needs verification for prose or conflicts, and gap for missing information. A mixed page uses the more cautious status and qualifies individual claims.
• EnvLinks: pass :links="[{ label: 'Staging', url: 'https://core.stg.lt.org' }]". An optional note explains uncertainty; omit url for an unknown destination. Keep induction links at the application's main entry point.
• AppCard: pass name, purpose, an array of tech labels, optional repo, docs and environments links. Use it in the application directory.
• Role tables: actions are rows; the columns are Anonymous, Researcher, Coordinator, Administrator and Editor. Use Yes, No or Partial and explain the scope underneath. Partial must not imply verified access where permissions are unknown.

Wrap wide Markdown tables in <div class="wide-table">, with blank lines around the table. Only tables should scroll horizontally. Keep the application page sections in the order Purpose, What it does, Technology, How it connects, Who can do what, Environments and links, Where to read more, Known gaps.

Diagrams and browser checks

Write diagrams in Mermaid fences. Use flowcharts for flows and topology, sequence diagrams for interactions and stateDiagram-v2 for lifecycles. Show uncertain handoffs as such, and do not draw a coordinator approving their own subject's work.

For a larger graph, wrap its Mermaid fence in <DiagramViewer title="Publication sequence"> and </DiagramViewer>, with blank lines around the fence. This adds an Expand diagram button below it, opening the same SVG in a native dialog with zoom, pan and Reset / fit. Smaller diagrams can stay inline.

Check every diagram in light and dark themes, plus a narrow viewport. Test expanded diagrams with zoom, drag, reset and Escape; closing must return focus to the trigger. Check navigation and local search. The build catches broken internal links but does not prove that client-rendered Mermaid diagrams work.

Screenshots and practical links

Use direct application and example-page URLs beside concepts so a newcomer knows where to look. Screenshots belong in public/screenshots/; give each an informative alternative description, source URL and capture date. Public examples supplement the repository evidence. Local admin screenshots must exclude credentials and sensitive details, and must be labelled as local sample data. Keep diagrams as Mermaid, never screenshots.

Commits

Work on main, use Conventional Commits such as docs(ecosystem): clarify publication handoff, and validate before committing. Do not add AI attribution trailers. Do not push without explicit approval. Husky checks commit messages using commitlint.

For maintainers: source references

These references require repository access. Everything needed to understand this page is explained above.

• brief
• package scripts
• the theme
• commitlint