Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (93 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

129 lines (93 loc) · 6.75 KB

Contributing to KernelCI Dashboard

KernelCI Dashboard is an open-source project and contributions of all kinds are welcome — bug reports, fixes, features, tests, and documentation. This guide explains how to get started, report issues, and submit changes.

Before you start

  • Read the README for an overview of the monorepo.
  • We recommend following the Onboarding guide to set up your environment and learn the project workflow. Start here if this is your first setup.
  • New to the project? Pick an issue labeled "good first issue".
  • There are a couple of extensions that may help you with linting and formatting your code. Consider installing ESLint and Prettier for your preferred code editor.
  • There are some of these to help with your Python development: Black, Flake8, and isort.

Useful links

Reporting bugs

Did you find a bug?

  • Ensure the bug was not already reported by searching on GitHub under our Issues
  • If the issue is reported, give it a thumbs up or comment on it to "upvote" it
  • If you're unable to find an open issue addressing the problem, open a new one
    • You can do it in this link
    • Include a clear title and description
    • Add steps to reproduce, logs, and screenshots if applicable
    • Provide a code sample or an executable test case demonstrating the expected behavior that is not occurring

How you can contribute

  • Report bugs with clear reproduction steps and logs
  • Propose enhancements with a brief problem statement and solution outline
  • Submit pull requests that fix issues or improve code/docs
  • Improve tests and developer experience

Development workflow

  1. Fork the repo and create a feature branch from main
  2. Keep PRs focused and small; one change per PR
  3. Follow Conventional Commits for commit messages (see Conventional Commits below)
  4. Run services locally (backend, frontend, or Docker) as described in the Onboarding guide; ensure builds and checks pass
  5. Update documentation and add tests when applicable
  6. Ensure the PR passes automated checks; see the suggested workflow in the "Make your code pass automated code checks" section

Guidelines for issues to create

We encourage actionable, well-defined issues. A good issue includes:

  • A clear title and description of the problem or feature
  • Steps to reproduce (for bugs), with logs and screenshots if applicable
  • For features: a brief explanation of the desired behavior and why it would benefit the project

Examples of good issues:

Staging environment

If you don't have access to the production database, you can point the frontend to the staging API at https://staging.dashboard.kernelci.org. To do so, set VITE_API_BASE_URL=https://staging.dashboard.kernelci.org in your dashboard/.env file (copy from dashboard/.env.example). Ask for access in the #webdashboard channel on KernelCI Discord.

Conventional Commits

Suggested commit format

We recommend following the Conventional Commits specification, which has the following format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types used in this project:

  1. fix: the commit patches a bug in the codebase.
  2. feat: the commit introduces a new feature to the codebase.
  3. feat! or fix!: the commit introduces a breaking API change.
  4. style: changes that do not affect the meaning of the code (formatting, whitespace).
  5. refactor: a code change that neither fixes a bug nor adds a feature.
  6. docs: documentation-only changes.
  7. test: adding or correcting tests.
  8. build: changes that affect the build system or external dependencies.
  9. ci: changes to CI configuration files and scripts (e.g., GitHub Actions).
  10. chore: other changes that don't modify src or test files.

When a commit introduces a breaking change in the API it is recommended to add a BREAKING CHANGE: footer.

To provide contextual information, a scope may be provided alongside the type. This needs to be contained within parentheses, for example, feat(parser): add ability to parse arrays.

You can find more details on the Conventional Commits specification site.

Make your code pass automated code checks

  • Backend
    • See backend/README.md for environment and commands
    • Run linting: poetry run flake8
    • Run type checks (optional but recommended): poetry run mypy
    • Run tests: poetry run pytest
    • Apply formatting with poetry run black . before committing; the backend/pre-commit and backend/pre-push hooks can help automate this — see backend/README.md for installation instructions
  • Frontend
    • See dashboard/README.md for scripts and commands
    • Run linting: pnpm lint
    • Run unit tests: pnpm test
    • Run end-to-end tests: pnpm e2e
    • Ensure the app builds: pnpm build
  • CI
    • Make a Pull Request and wait for someone to approve the execution of GitHub Actions; if any check fail, they must be fixed for your PR to be approved

Pull requests

  • Use a title that follows the Conventional Commits format (e.g., fix(backend): correct pagination offset)
  • Reference related issues (e.g., Closes #123)
  • Describe the motivation, approach, and any trade-offs
  • Include screenshots/GIFs for UI changes
  • Wait for someone to approve the execution of GitHub Actions. Ensure CI is green before requesting reviews
  • Take a look at merged PRs to see examples of good descriptions and commit messages

Communication and help

  • Ask questions or seek feedback by opening an issue
  • You can also reach the team in the #webdashboard channel on the KernelCI Discord

Licensing

By contributing, you agree that your contributions will be licensed under the project's LICENSE file.