diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md new file mode 100644 index 0000000..f8a7b5e --- /dev/null +++ b/COLLABORATOR_GUIDE.md @@ -0,0 +1,119 @@ +# Collaborator Guide + +- [Issues and Pull Requests](#issues-and-pull-requests) +- [Accepting Modifications](#accepting-modifications) + - [Involving the Web Infrastructure Team](#involving-the-web-infrastructure-team) +- [Technologies Used in the Worker](#technologies-used-in-the-worker) +- [Code Editing](#code-editing) + - [Structure of this Repository](#structure-of-this-repository) +- [Testing](#testing) + - [Unit Testing](#unit-testing) + - [End-to-End Testing](#end-to-end-testing) +- [Remarks on Technologies Used](#remarks-on-technologies-used) +- [Additional Clarification](#additional-clarification) + +This document contains information for Collaborators of the Node.js release worker project regarding maintaining code, documentation, and issues. + +Collaborators should be familiar with the guidelines for new contributors in [CONTRIBUTING.md](./CONTRIBUTING.md) + +## Issues and Pull Requests + +Courtesy should always be shown to individuals submitting issues and pull requests to the Node.js Release Worker project. + +Collaborators should feel free to take full responsibility for managing issues and pull requests they feel qualified to handle, as long as this is done while being mindful of these guidelines, the opinions of other Collaborators and guidance of the Web Infrastructure Group. + +Collaborators may close any issue or pull request they believe is not relevant to the future of the Node.js project. Where this is unclear, the issue should be left open for several days for additional discussion. Where this does not yield input from Node.js Collaborators or additional evidence that the issue has relevance, then the issue may be closed. Remember that issues can always be re-opened if necessary. + +## Accepting Modifications + +All code and documentation modifications should be performed via GitHub pull requests. Only the Web Infrastructure Team can merge their work and should do so carefully. + +All pull requests must be reviewed and accepted by a Collaborator with sufficient expertise who can take full responsibility for the change. In the case of pull requests proposed by an existing Collaborator, an additional Collaborator is required for sign-off. + +Pull Requests can only be merged after all CI Checks have passed. + +In some cases, it may be necessary to summon a qualified Collaborator to a pull request for review by @-mention. + +If you are unsure about the modification and are not prepared to take full responsibility for the change, defer to another Collaborator. + +We recommend collaborators follow the guidelines on the [Contributing Guide](./CONTRIBUTING.md) for reviewing and merging Pull Requests. + +### Involving the Web Infrastructure Team + +Collaborators may opt to elevate pull requests or issues to the group for discussion by mentioning @nodejs/web-infra. This should be done where a pull request: + +- Has a significant impact on the codebase +- Is inherently controlversial; or +- Has failed to reach a consensus amongst the Collaborators who are actively participating in the discussion. + +The Web Infrastructure should be the final arbiter where needed. + +## Technologies Used in the Worker + +The Node.js Release Worker is built upon [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Cloudflare R2](https://developers.cloudflare.com/r2/). + +The Worker also uses several other Open Source libraries (not limited to) listed below: + +- [AWS S3 client](https://www.npmjs.com/package/@aws-sdk/client-s3) is used for interacting with R2's S3 entrypoint. +- [Handlebars.js](https://www.npmjs.com/package/handlebars) is used for rendering templated pages. +- [Sentry](https://sentry.io/about) is used for error reporting. +- [Zod](https://zod.dev/?id=introduction) is used for error reporting. + +## Code Editing + +### Structure of this Repository + +- `src/` - Worker +- `scripts/` - Multi-purpose scripts +- `tests/` - Tests for the worker + +## Testing + +Each new feature or bug fix should be accompanied by a unit or E2E test (when valuable). We use Node's test runner and Miniflare for our E2E tests. + +### Unit Testing + +Unit Tests are fundamental to ensure that code changes do not disrupt the functionalities of the Worker: + +- Unit Tests should be written as `.test.ts` files in the [tests/unit/](./tests/unit/) directory. +- They should cover utilities as well as any component that can be broken down and individually tested. +- We utilize Node's [Test Runner](https://nodejs.org/api/test.html) and [Assert](https://nodejs.org/api/assert.html) APIs. +- External services used in the worker should be mocked with Undici. If the service cannot be mocked with Undici, it should be mocked with a HTTP server via Node's `createServer` API. + +### End-to-End Testing + +E2E Tests are fundamental to ensure that requests made to the worker behave as expected: + +- E2E Tests should be written as `.test.ts` files in the [tests/e2e/](./tests/e2e/) directory. +- They should cover the various contexts of a request that could be sent to the worker from an external client. +- We utilize Node's [Test Runner](https://nodejs.org/api/test.html) and [Assert](https://nodejs.org/api/assert.html) APIs. +- A local version of the Worker is ran with Miniflare. +- Like Unit Tests, any external services should be mocked for these tests as well. + +## Remarks on Structure and Background + +### Why Workers and R2? + +We chose [Cloudflare Workers](https://workers.cloudflare.com) because it is mostly straight-forward, reliable, community-oriented, and the support backing it. + +[Cloudflare R2](https://www.cloudflare.com/developer-platform/r2/) was chosen for similar reasoning, but also noteably its integration with Workers along with no egress fees. + +Cloudflare has also graciously provided the OpenJS Foundation with an Enterprise account in addition to supporting us with any technical issues or questions we have faced. + +### What is the 'origin'/'DO' server? + +This refers to the singular server instance that hosted the release assets (binaries, docs, shasums) among other things. +This Worker aims to replace that server when it comes to serving the release assets. + +### Bucket File Structure + +The bucket's file structure is a 1:1 mapping to the file structure of the release assets on the origin server. + +### Frontend Bits + +The directory listing page is the only frontend page that the Worker serves non-statically. For simplicitly, it is a pre-compiled Handlebars template. +Should any other pages be added to this worker, they should do the same unless a consensus is reached by the Collaborators. + +## Additional Clarification + +If you have any further questions, please feel free to reach out in [an Issue](https://github.com/nodejs/release-cloudflare-worker/issues/new) or the `#r2-website-migration` channel in the [OpenJS Foundation Slack](https://openjsf.org/collaboration). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7d3a028 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,207 @@ +# Node.js Release Worker Contributing Guide + +Thank you for your interest in contributing to the Node.js Release Worker. Before you proceed, briefly go through the following, + +- [Contributing](#contributing) + - [Becoming a Collaborator](#becoming-a-collaborator) +- [Getting Started](#getting-started) + - [CLI Commands](#cli-commands) +- [Commit Guidelines](#commit-guidelines) + - [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Policy](#pull-request-policy) + - [Before Merging](#before-merging) + - [When Merging](#when-merging) +- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11) + +## Contributing + +Any individual is welcome to contribute to the Node.js Release Worker. The repository currently has two kinds of contribution personas: + +- A **Contributor** is any individual who creates an issue/pull request, comments on an issue or pull request, or contributes in some other way. +- A **Collaborator** is a contributor with write access to the repository. See [here](#becoming-a-collaborator) on how to become a collaborator. + +You can find more details and guides about Collaborating with this repository through our [Collaborator Guide](./COLLABORATOR_GUIDE.md). + +### Becoming a Collaborator + +A collaborator of the Node.js Release Worker repository is a member of the Node.js Web Infrastructure Team. + +The Web Infrastructure Team is responsible for maintaining the Infrastructure behind Node.js' Web Presence. It is expected that team members have significant knowledge about the infrastructure behind Node.js' Web Presence. + +Note that regular contributors do not need to become "Collaborators" as any contribution is appreciated (even without a status), and a Collaborator status is a formality that comes with obligations. + +If you're an active contributor seeking to become a member, we recommend you contact one of the existing Team Members for guidance. + +
+ What's the process for becoming a Collaborator? + +- You must be actively contributing to this repository. +- Contributions must include significant code reviews or code modifications. +- A nomination must be done by an existing Team Member of the Web Infra team with an issue. + - The Issue must explain and describe why the nominated person is a good addition to the team + - The Issue must contain links to the relevant contributions, including but not limited to: + - Code Reviews. + - Comments on issues and PRs. + - Authoring of PRs and issues. +- The nomination must have at least three existing members of the Website Team agree with the nomination. + - This can be done through commenting with "agreement" (showing support) or reacting to the Issue with a 👍 (Thumbs-up Emoji). +- The Issue must be open for at least 72 hours without an objection from an existing member of the Website Team. + - The nomination cannot pass until all open objections are resolved. + - Objections from the TSC or Core Collaborators are also counted as valid objections. + +
+ +## Getting Started + +The steps below will give you a general idea of how to prepare your local environment for the Worker and general steps for getting things done and landing your contribution. + +1. Click the fork button in the top right to clone the [Node.js Release Worker Repository](https://github.com/nodejs/release-cloudflare-worker/fork) + +2. Clone your fork using SSH, GitHub CLI, or HTTPS. + + ```bash + git clone git@github.com:/release-cloudflare-worker.git # SSH + git clone https://github.com//release-cloudflare-worker.git # HTTPS + gh repo clone /release-cloudflare-worker # GitHub CLI + ``` + +3. Change into the `release-cloudflare-worker` directory. + + ```bash + cd release-cloudflare-worker + ``` + +4. Create a remote to keep your fork and local clone up-to-date. + + ```bash + git remote add upstream git@github.com:nodejs/release-cloudflare-worker.git # SSH + git remote add upstream https://github.com/nodejs/release-cloudflare-worker.git # HTTPS + gh repo sync nodejs/release-cloudflare-worker # GitHub CLI + ``` + +5. Create a new branch for your work. + + ```bash + git checkout -b name-of-your-branch + ``` + +6. Run the following to install the dependencies and start a local preview of your work. + + ```bash + npm install + ``` + +7. Perform your changes. In case you're unfamiliar with the structure of this repository, we recommend a read on the [Collaborator Guide](./COLLABORATOR_GUIDE.md). + +8. Perform a merge to sync your current branch with the upstream branch. + + ```bash + git fetch upstream + git merge upstream/main + ``` + +9. Run the following to confirm that linting and formatting are passing. + + ```bash + npm run format + npm run test:unit + npm run test:e2e + ``` + +10. Once you're happy with your changes, add and commit them to your branch, then push the branch to your fork. + + ```bash + git add . + git commit -m "some message" + git push -u origin name-of-your-branch + ``` + + > [!IMPORTANT]\ + > Before committing and opening a Pull Request, please go first through our [Commit](#commit-guidelines) and [Pull Request](#pull-request-policy) guidelines outlined below. + +11. Create a Pull Request. + +### CLI Commands + +This repository contains a few scripts and commands for performing numerous tasks. The most relevant ones are described below. + +
+ Commands for Testing, Maintaining, and Contributing to the Worker + +- `npm run format` Formats the code to the repository's standards. +- `npm run lint` Lints the code to the repository's standards. +- `npm run test:unit` Runs the [Unit Tests](./COLLABORATOR_GUIDE.md#unit-tests) to ensure individual components are working as expected. +- `npm run test:e2e` Runs the [E2E Tests](./COLLABORATOR_GUIDE.md#e2e-tests) to ensure requests act as expected. +- `npm run build:handlebars` Compiles the Handlebars templates. **Required for any changes to the templates to take affect**. + +
+ +
+ Commands for Running the Worker + +- `npm start` Runs a local [workerd](https://github.com/cloudflare/workerd) instance with the Worker on your machine in remote mode. + +
+ +## Commit Guidelines + +This project follows the [Conventional Commits][https://www.conventionalcommits.org/en/v1.0.0/] specification. + +Commits should be signed. You can read more about [Commit Signing][https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits] here. + +### Commit Message Guidelines + +- Commit messages must include a "type" as described on Conventional Commits +- Commit messages **must not** end with a period `.` + +## Pull Request Policy + +This policy governs how contributions should land within this repository. The lines below state the checks and policies to be followed before merging and in the act of merging. + +### Before Merging + +We recommend reading our [Collaborator Guide](./COLLABORATOR_GUIDE.md) for in-depth details on how we accept contributions into this repository. The list below describes some merging and approval rules adopted in this repository. + +- Pull Requests must be open for at least 48 hours (or 72 hours if the PR was authored on the weekend). + - If the Pull Request was marked as a draft, it must be marked "Ready for Review" for at least 48 hours (or 72 hours if done on a weekend) before being merged. + - Pull Requests may be immediately merged if they contain critical fixes, short errata (e.g. typos), or any critical change considered a "showstopper" for the website's operation or security. + - This kind of Pull Request should only be done by existing Collaborators and/or signed off by administrators/maintainers. + - This rule cannot be used for updates on the `COLLABORATOR_GUIDE.md`, `CONTRIBUTING.md`, `CODEOWNERS`, GitHub Actions, or any other document that changes the governing policies of this repository. + - Pull Requests containing small bug fixes, small feature changes, or other non-critical/highly-impacting changes not covered by the previous rule that allows PRs to be merged immediately might be "fast-tracked". This means they can be merged before the usual 48 hour time period. + - The person that is fast-tracking the PR (adding the label) must be a Collaborator. + - The person that is fast-tracking the PR must also comment on the PR that they're requesting the PR to be fast-tracked + - Fast-tracking cannot be used for updates on the `COLLABORATOR_GUIDE.md`, `CONTRIBUTING.md`, GitHub Actions, or any security-impacting file or document that changes the governing policies of this repository. +- There must be no objections after 48 hours (or 72 hours if the PR was authored on the weekend). + - If there are disagreements consensus should be sought. Lack of consensus might require escalation to the Web Infrastructure Team Maintainers. +- At least one approval is required for any PR to be merged. +- Tests must be included in Pull Requests for new features or bug fixes. You are responsible for fixing any test(s) that fail. + +Each contribution is accepted only if there is no objection to it by a collaborator. During the review, collaborators may request that a specific contributor who is an expert in a particular area give an "LGTM" before the PR can be merged. + +If an objection is raised in a pull request by another collaborator, all collaborators involved should try to arrive at a consensus by addressing the concerns through discussion, compromise, or withdrawal of the proposed change(s). + +### When Merging + +- All required Status-checks must have passed. +- Please make sure that all discussions are resolved. +- [`Squash`](https://help.github.com/en/articles/about-pull-request-merges#squash-and-merge-your-pull-request-commits) pull requests made up of multiple commits + +## Developer's Certificate of Origin 1.1 + +``` +By contributing to this project, I certify that: + +- (a) The contribution was created in whole or in part by me and I have the right to + submit it under the open source license indicated in the file; or +- (b) The contribution is based upon previous work that, to the best of my knowledge, + is covered under an appropriate open source license and I have the right under that + license to submit that work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am permitted to submit under a + different license), as indicated in the file; or +- (c) The contribution was provided directly to me by some other person who certified + (a), (b) or (c) and I have not modified it. +- (d) I understand and agree that this project and the contribution are public and that + a record of the contribution (including all personal information I submit with it, + including my sign-off) is maintained indefinitely and may be redistributed consistent + with this project or the open source license(s) involved. +``` diff --git a/README.md b/README.md index 1387c28..56e5947 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,51 @@ -# release-cloudflare-worker +

+
+ + + + + + +

-New infra for serving Node.js downloads and documentation. +

+ A Cloudflare Worker that serves Node.js downloads and documentation. +

-For more information, check out [nodejs/build#3461](https://github.com/nodejs/build/issues/3461). +

+ + MIT License + +

-## Dev Setup +## Contributing -View [docs/dev-setup.md](./docs/dev-setup.md) +This project adopts the Node.js [Code of Conduct](https://github.com/nodejs/admin/blob/main/CODE_OF_CONDUCT.md). + +Any person that wants to contribute to the Worker is welcome! Please read the [Contribution Guidelines](CONTRIBUTING.md) to better understand the structure of this repository. + +### Deployment + +The Worker is deployed to Cloudflare via [a Github Action](https://github.com/nodejs/release-cloudflare-worker/blob/main/.github/workflows/deploy.yml). + +There is a staging environment available at https://dist-worker-staging.nodejs.workers.dev/. The Worker is automatically deployed to this environment when commits are merged into the `main` branch. + +The production environment is available at https://r2.nodejs.org. Deployments here are done manually by a Collaborator. + +## Relevant Links + +- [Code of Conduct](https://github.com/nodejs/admin/blob/main/CODE_OF_CONDUCT.md) + +- [Contribution Guidelines](CONTRIBUTING.md) + +- [Collaborator Guideline](COLLABORATOR_GUIDE.md) ## License This repo is licensed under the terms of the [MIT License](./LICENSE.md). It is based off of [Kotx's render worker](https://github.com/kotx/render), which is also licensed under the MIT license. + +## Thanks + +- Thanks to all the contributors and collaborators that make this project possible. +- Thanks to [Cloudflare](https://cloudflare.com) for providing the infrastructure that serves the Worker under their Open Source Initiative in addition to immense support. +- Thanks to [Sentry](https://sentry.io/welcome) for providing an open source license for their error reporting software.