Contributing

XyraPanel grows through community input. Contributions of all types are welcome: fixes, features, documentation, test coverage, examples, and issue reports. Before getting started, review the repository README and scan open issues to avoid duplication.

Core principles

• Keep work scoped to a single problem.
• Communicate clearly and stay focused on the topic.
• Follow the project’s conventions for style, tests, commits, and PR structure.

Commit Conventions

We follow Conventional Commits to keep history structured and changelogs automated.

• fix: and feat: are reserved for changes that modify behavior or logic.
• Non-functional changes use docs: or chore:.
  Example:
  • Wrong: fix: typo
  • Correct: docs: fix typo
• Use scopes to indicate the area affected (e.g., auth, admin, ui, api).
  Example:
  feat(auth): add user token validator
• PR titles must also follow these conventions.
• All PRs will be finalized by the project maintainer.

Code & documentation standards

• Match the existing code style and ESLint rules.
• Provide tests for new features or bug fixes when appropriate.
• Update documentation for any user facing modification.
• Use descriptive branch names like fix/312-sync-headers or feat/auth-oauth-flow.

Formatting rules

This project does not use Prettier.
ESLint handles formatting.
Disable Prettier in your editor to avoid unwanted changes.
Use the following to format:

• pnpm run lint:fix

Local workflow

1. Fork and clone the repository.
2. Create a branch:
   git checkout -b <type>/<short-description>
3. Implement your change and add tests when needed.
4. Run linting, type checks, and tests (see README).
5. Build locally when relevant.

Pull requests

1. Push your branch and open a PR targeting main (or the branch specified in the issue).
2. Your PR description must include:
   • What the change does
   • Why it was made
   • Steps to reproduce (for bug fixes)
   • How to test it
   • Migration notes (if any)
3. Link related issues.
4. Ensure CI, linting, and type checks pass.
5. Stay available for follow up questions.
6. All PRs are finalized by a project maintainer, who determines the merge method (squash, rebase, or standard merge).

PR checklist

• Issue exists or discussion occurred
• Branch name follows conventions
• Tests added or updated
• CI, lint, and type checks succeed
• Docs updated if needed
• Commits follow Conventional Commits
• PR includes testing steps

Reporting issues

When opening an issue:

• Search for existing reports first.
• Provide a clear title and minimal reproduction.
• Include logs, environment details, version numbers, and relevant config.
• If possible, link a small test repo or sandbox.
• Explain expected behavior, actual behavior, and severity.

Significant or breaking work

For large changes:

• Open an issue or proposal before starting.
• Include an outline, migration notes, and release implications.
• Draft PRs are welcome for early feedback.

Licensing

By submitting contributions, you confirm you have the right to do so and that your work will be published under the project’s MIT license.

Getting started

Issues labeled good first issue or help wanted are suitable entry points.
Maintainers respond as time allows.