Thank you for contributing your time and expertise to the OpenSSF Scorecard Monitor project. This document describes the contribution guidelines for the project.
Important
Before you start contributing, you must read and abide by our Code of Conduct.
Additionally, the Linux Foundation (LF) requires all contributions include per-commit sign-offs.
Ensure you use the -s or --signoff flag for every commit.
For more details, see the LF DCO wiki or this Pi-hole signoff guide.
- Contributing code
- Contributing steps
- Running the project locally
- Installing the project dependencies
- Running tests
- Linting the codebase
- What to do before submitting a pull request
- PR Process
- Where the CI Tests are configured
- Updating Docs
- Create a GitHub account
- Create a personal access token
- Set up your development environment
You must install these tools:
If you're unfamiliar with Node.js, there are plenty of articles, resources, and books. We recommend starting with several resources from the official Node.js website:
- Identify an existing issue you would like to work on, or submit an issue describing your proposed change to the repo in question.
- The maintainers will respond to your issue promptly.
- Fork this repo, develop, and test your code changes.
- Submit a pull request.
Currently, this project is consumed as a GitHub Action, so local development is quite limited. In order to test the full workflow, you can consume directly your fork and branch from another project or by adding a new workflow in your fork.
Aside from this, it is possible to test certain things locally, like the utils.js file. Check the test folder _tests_/utils.test.js to get a better idea.
First, check that you are using Node v20+ and then execute npm ci instead of npm i or npm install as you want to mimic the pipeline steps in order to avoid discrepancies later on with the dist/ as the dependencies are included there.
Currently, the project is using Jest and Snapshot Testing.
You have several options to run the tests:
npm run test: this will run the testsnpm run test:update: this will run the tests and update the snapshotsnpm run test:coveragethis will run the tests and generate a coverage report as terminal output and in HTML format that can be found in thecoverage/foldernpm run test:watch: this will run the tests when you make changes in any of the project's files.
This project uses JavaScript Standard Style. If you are not familiar with this style, you can make your changes and run npm run lint:fix when you are ready. The linter will fix most of the issues for you and it will highlight any additional issue that requires manual work.
To check that your files are properly linted, you can run npm run lint. This review won't make changes to your files.
The following are the targets that can be used to test your changes locally:
| Command | Description | Is called in the CI? |
|---|---|---|
npm run lint:fix |
force the JS Standard style on your files | checked as npm run lint |
npm run test:coverage |
Run the unit tests | Yes |
npm run build |
Use ncc to generate the dist/ folder |
yes, it has a validation step |
Every PR should be tagged with the relevant labels. This work is done by the maintainers exclusively.
Individual commits should not be tagged separately, but will generally be assumed to match the PR. For instance, if you have a bugfix in with a breaking change, it's generally encouraged to submit the bugfix separately, but if you must put them in one PR, you should mark the whole PR as breaking.
Note
Once a maintainer reviews your code, please address feedback without rebasing when possible.
This includes synchronizing your PR
with main. The GitHub review experience is much nicer with traditional merge commits.
- See the action files to check its tests, and the scripts used on it.
The documentation can be found in the README. Any changes that are merged to main will be reflected directly on the GitHub Actions Marketplace, so documentation changes do not require a specific release.