Skip to content

Commit f843400

Browse files
UlisesGasconUlisesGascon
committed
docs: add a CONTRIBUTING guide
1 parent 6adbd3d commit f843400

File tree

1 file changed

+159
-0
lines changed

1 file changed

+159
-0
lines changed

‎CONTRIBUTING.md

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Contributing to the Dashboard
2+
3+
Contributions to the Dashboard include code, documentation, answering user questions, running the project's infrastructure, and advocating for all types of users.
4+
5+
The project welcomes all contributions from anyone willing to work in good faith with other contributors and the community. No contribution is too small, and all contributions are valued.
6+
7+
The project has an open governance model. Individuals making significant and valuable contributions are made committers and given commit-access to the project.
8+
9+
## Contents
10+
11+
* [Code of Conduct](#code-of-conduct)
12+
* [Issues](#issues)
13+
* [Pull Requests](#pull-requests)
14+
* [Current Initiatives](#current-initiatives)
15+
* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
16+
17+
## Code of Conduct
18+
19+
The project has a [Code of Conduct](/CODE_OF_CONDUCT.md) to which all contributors must adhere.
20+
21+
## Issues
22+
23+
You have several templates available:
24+
25+
* [Asking for General Help](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues/new?assignees=&labels=&projects=&template=other.md&title=)
26+
* [Request a New Feature](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues/new?assignees=&labels=feature-request&projects=&template=feature_request.md&title=)
27+
* [Report a Bug](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D)
28+
* [Other](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues/new?assignees=&labels=&projects=&template=other.md&title=)
29+
30+
## [Pull Requests](./doc/contributing/pull-requests.md)
31+
32+
Here are some recommendations for creating PRs in this project.
33+
34+
Creating a high-quality Pull Request (PR) helps maintainers review your contribution efficiently and ensures it aligns with the project's standards. Follow these steps to make your PR outstanding:
35+
36+
### 1. Understand the Project's Guidelines
37+
38+
- **Read the [Contributing Guidelines](CONTRIBUTING.md):** Check for any specific requirements for this project.
39+
- **Follow the [Code of Conduct](CODE_OF_CONDUCT.md):** Ensure respectful communication and behavior.
40+
41+
### 2. Before You Start
42+
43+
- **Create an Issue (if required):** Link your PR to an issue if it addresses a bug or feature request.
44+
- **Sync with the Main Branch:** Update your fork or branch with the latest changes to avoid conflicts.
45+
- **Focus Your Work:** Address one issue or feature per PR.
46+
- **Ensure the Work Is Expected:** Avoid submitting a PR when there is an ongoing discussion on the topic, as this might require you to make significant changes.
47+
- **Avoid Duplications:** Check open PRs to avoid duplications.
48+
49+
### 3. Writing the Code
50+
51+
- **Follow Coding Standards:** Use [Standard](https://standardjs.com/) and refer to [the linter commands](/README.md#linting) to resolve any issues.
52+
- **Write Tests:** Add or update tests to cover your changes. Check [the testing section](/README.md#testing).
53+
- **Keep Changes Minimal:** Avoid unrelated changes or large rewrites, as this will make your PR hard to review. We prefer many small PRs rather than one large PR.
54+
55+
### 4. Writing the PR
56+
57+
- **Descriptive Title:** Use a clear and concise title that summarizes the change.
58+
- **Detailed Description:** Include the following in the description:
59+
- **What:** Explain what the PR does.
60+
- **Why:** Describe why the change is necessary.
61+
- **How:** Summarize how you implemented the change.
62+
- **Related Issue:** Link any relevant issues (e.g., `Closes #123`).
63+
- **Screenshots/Logs (if applicable):** Provide evidence of your changes for visual or functional updates.
64+
65+
### 5. Review Checklist
66+
67+
Before submitting your PR:
68+
- [ ] Code is linted and passes all style checks.
69+
- [ ] Tests are added, updated, and pass.
70+
- [ ] Documentation is updated (if applicable).
71+
- [ ] The branch is up-to-date with the main branch.
72+
- [ ] Commit messages are clear and follow the project's guidelines.
73+
74+
### 6. Submit and Engage
75+
76+
- **Submit the PR:** Push your branch and open the PR using the project's preferred platform (e.g., GitHub).
77+
- **Review Automated Comments:** Pipelines in this project might auto-suggest changes or additional steps based on the submitted changes. Please review them.
78+
- **Check CI Results:** This project includes a CI pipeline that will check your PR for linting, tests, migrations, and more. Please review the logs in case of errors.
79+
- **Engage with Feedback:** Respond promptly to reviewer comments and make necessary updates.
80+
- **Be Patient:** Reviewers may take time to go through your PR.
81+
- **Ask for Help Anytime:** Contributing to an open-source project might be challenging. Please share any concerns or ask for clarifications when needed. We are here to help you.
82+
83+
By following these steps, you'll create a high-quality PR that is easier to review and more likely to be accepted. Thank you for contributing!
84+
85+
## Current Initiatives
86+
87+
Here you can find the best ways to make meaningful contributions to the project.
88+
89+
### Add Compliance Checks
90+
91+
We are looking for contributors to implement compliance checks in the Dashboard. Here is a process to achieve this:
92+
93+
1. Check the open issues related to [compliance checks](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aclosed+label%3Acompliance-checks). Focus on issues with a title following this pattern: `Add Compliance check: *`, such as [Add Compliance check: githubOrgMFA](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues/43).
94+
95+
2. Engage in the conversation and request to lead or contribute to the implementation. A key part of this process is defining a way to implement the compliance check (e.g., data usage, alerting criteria, etc.).
96+
97+
3. Start development by completing the following tasks:
98+
99+
#### Development Steps
100+
101+
- **1. Define a Good Implementation ([Example](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues/43#issuecomment-2524594504)):**
102+
- Read the documentation (guidelines, best practices, etc.).
103+
- Brainstorm the implementation details (logic, alerts, tasks, validations, edge cases, etc.).
104+
- Reach an agreement on the implementation details before starting.
105+
106+
- **2. Update Check Record ([Example](https://github.com/secure-dashboards/openjs-foundation-dashboard/commit/55eaac59920a5229ef9eeaf859943578a66d1aeb)):**
107+
- Update the `compliance_checks` row with fields like `how_to_url`, `implementation_status`, `implementation_type`, and `implementation_details_reference`.
108+
- Test migration scripts using `npm run db:migrate` and `npm run db:rollback`.
109+
- Update the database schema with `npm run db:generate-schema`.
110+
111+
- **3. Implement the Business Logic ([Validator Example](https://github.com/secure-dashboards/openjs-foundation-dashboard/commit/44c41d119f0daefb7b2e496ba35d5ab65bcc319b) and [Check Example](https://github.com/secure-dashboards/openjs-foundation-dashboard/commit/6f1e16129ee0d01a1b9b536cd2dc6090b048b71f)):**
112+
- Add the specific validator in `src/checks/validators/index.js`.
113+
- Add the check logic in `src/checks/complianceChecks`.
114+
- Ensure the check is applicable to the organization (`isCheckApplicableToProjectCategory`).
115+
- Calculate `severity` accurately (`getSeverityFromPriorityGroup`).
116+
- Update relevant database tables (`compliance_checks_alerts`, `compliance_checks_tasks`, `compliance_checks_results`).
117+
118+
- **4. Ensure It Works as Expected:**
119+
- Add unit tests for the validator check.
120+
- Add integration test cases for the check.
121+
- Verify all tests pass.
122+
- Run `check run --name {check_code_name}` and verify database changes. Update the seed script if necessary (`npm run db:seed`).
123+
124+
- **5. Update the Website ([Example](https://github.com/secure-dashboards/openjs-security-program-standards/pull/9)):**
125+
- Review content at `https://openjs-security-program-standards.netlify.app/details/{check_code_name}`.
126+
- Create a PR to include check calculation details and mitigation information.
127+
128+
### Other
129+
130+
Any issue labeled [help wanted](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) or [good first issue](https://github.com/secure-dashboards/openjs-foundation-dashboard/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) is a great opportunity to help the project.
131+
132+
## Developer's Certificate of Origin 1.1
133+
134+
135+
```text
136+
By making a contribution to this project, I certify that:
137+
138+
(a) The contribution was created in whole or in part by me and I
139+
have the right to submit it under the open source license
140+
indicated in the file; or
141+
142+
(b) The contribution is based upon previous work that, to the best
143+
of my knowledge, is covered under an appropriate open source
144+
license and I have the right under that license to submit that
145+
work with modifications, whether created in whole or in part
146+
by me, under the same open source license (unless I am
147+
permitted to submit under a different license), as indicated
148+
in the file; or
149+
150+
(c) The contribution was provided directly to me by some other
151+
person who certified (a), (b) or (c) and I have not modified
152+
it.
153+
154+
(d) I understand and agree that this project and the contribution
155+
are public and that a record of the contribution (including all
156+
personal information I submit with it, including my sign-off) is
157+
maintained indefinitely and may be redistributed consistent with
158+
this project or the open source license(s) involved.
159+
```

0 commit comments

Comments
 (0)