docs/improve contributing docs (#1812)

* docs: Update contributions guidelines

* docs: add missing links to README.md

* docs: apply PR suggestions on contribution files

- closes #1810

* fix: remove unnecessary call for click

Author: dede999

CONTRIBUTING.md

@@ -5,22 +5,26 @@ KernelCI Dashboard is an open-source project and contributions of all kinds are
 ## 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.
-- New to the project? Pick an issue labeled "good first issue".
+- We recommend following the [Onboarding guide](./docs/Onboarding.md) 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"](https://github.com/kernelci/dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+- There are a couple of extensions that may help you with linting and formatting your code. Consider installing [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) for your preferred code editor.
+- There are some of these to help with your Python development: [Black](https://black.readthedocs.io/en/stable/), [Flake8](https://flake8.pycqa.org/en/latest/), and [isort](https://pycqa.github.io/isort/).
 
 ## Useful links
 
 - README: [./README.md](./README.md)
 - Onboarding guide: [./docs/Onboarding.md](./docs/Onboarding.md)
-- Open issues: https://github.com/kernelci/dashboard/issues
-- Good first issues: https://github.com/kernelci/dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+- Open issues on [this page](https://github.com/kernelci/dashboard/issues)
+- Good first issues on [this page](https://github.com/kernelci/dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
 
 ## Reporting bugs
 
 #### Did you find a bug?
 
-- Ensure the bug was not already reported by searching on GitHub under Issues: https://github.com/kernelci/dashboard/issues
-- If you're unable to find an open issue addressing the problem, open a new one: https://github.com/kernelci/dashboard/issues/new
+- **<ins>Ensure the bug was not already reported</ins>** by searching on GitHub under [our Issues](https://github.com/kernelci/dashboard/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](https://github.com/kernelci/dashboard/issues/new)
   - 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
@@ -41,11 +45,26 @@ KernelCI Dashboard is an open-source project and contributions of all kinds are
 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:
+- [Display Test Results Hierarchically: Group Test Cases Under Their Parent Test Suites](https://github.com/kernelci/dashboard/issues/1800)
+- [Tree Details Page: each grouping of execution items in the tests execution list](https://github.com/kernelci/dashboard/issues/286)
+
+## 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](https://discord.gg/GRv3RhUa6P).
+
 ## Conventional Commits
 
 ### Suggested commit format
 
-We recommend following the Conventional Commits specification (https://www.conventionalcommits.org/en/v1.0.0/#specification), which has the following format:
+We recommend following the [**Conventional Commits specification**](https://www.conventionalcommits.org/en/v1.0.0/#specification), which has the following format:
 
 ```shell
 <type>[optional scope]: <description>
@@ -55,36 +74,49 @@ We recommend following the Conventional Commits specification (https://www.conve
 [optional footer(s)]
 ```
 
-Types usually are:
+Types used in this project:
 
-1. fix: meaning 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. Other types are allowed, for example: build, cli, test, docs.
+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.
+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 parenthesis, for example, `feat(parser): add ability to parse arrays`.
+ 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 linters, tests, and type checks locally; apply formatting
+  - See [backend/README.md](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](backend/README.md) for installation instructions
 - Frontend
-  - See dashboard/README.md for scripts and commands
-  - Run linters, tests, and type checks; ensure the app builds
+  - See [dashboard/README.md](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
+- 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
@@ -94,4 +126,4 @@ You can find more details on the Conventional Commits specification site.
 
 ## Licensing
 
-By contributing, you agree that your contributions will be licensed under the project’s LICENSE file.
+By contributing, you agree that your contributions will be licensed under the project's [LICENSE](./LICENSE) file.

README.md

@@ -12,10 +12,10 @@ system from the [KernelCI Foundation](https://kernelci.org/).
 What we have as a repository is a monorepo containing the *dashboard* (the web application) and a *backend*.
 
 ### Dashboard
-A web app built with [React](https://react.dev/) + [Typescript](https://www.typescriptlang.org/), to see more information check the dashboard [README](dashboard/README.md).
+ A web app built with [React](https://react.dev/) + [TypeScript](https://www.typescriptlang.org/), to see more information check the dashboard [README](dashboard/README.md).
 
 ### Backend
-A Python http server built with [Django](https://www.djangoproject.com/) + [DRF](https://www.django-rest-framework.org/), to see more information check the backend [README](/backend/README.md).
+A Python http server built with [Django](https://www.djangoproject.com/) + [DRF](https://www.django-rest-framework.org/), to see more information check the backend [README](backend/README.md).
 
 
 ## Quick run
@@ -101,7 +101,7 @@ sudo -E docker compose up --build -d
 ```
 Or you can also run the env exports and docker compose within the root user by running `sudo su`.
 
-> Tip: you can create a quick script to set all the necessary envs and start the services. This will also allow docker to see the environment variables correclty. Example:
+> Tip: you can create a quick script to set all the necessary envs and start the services. This will also allow docker to see the environment variables correctly. Example:
 
 ```sh
 export DB_USER=email@email.com
@@ -117,6 +117,8 @@ docker compose up --build
 
 ## Deploying to production
 
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for full deployment instructions covering development, staging, and production scenarios.
+
 To deploy to prod you need to push a tag in the `release/YYYYMMDD.N` format
 like: `release/20240910.0`