diff --git a/.github/ISSUE_TEMPLATE/meeting.md b/.github/ISSUE_TEMPLATE/meeting.md index c4c2249..527876c 100644 --- a/.github/ISSUE_TEMPLATE/meeting.md +++ b/.github/ISSUE_TEMPLATE/meeting.md @@ -1,25 +1,44 @@ -## Date/Time - -| Timezone | Date/Time | -|----------|-----------| -<%= [ +<% const timezones = [ 'America/Los_Angeles', 'America/Denver', 'America/Chicago', + 'America/Bogota', 'America/New_York', + 'UTC', 'Europe/London', - 'Europe/Amsterdam', + 'Europe/Madrid', + 'Europe/Paris', + 'Europe/Warsaw', 'Europe/Moscow', 'Asia/Kolkata', 'Asia/Shanghai', 'Asia/Tokyo', 'Australia/Sydney' -].map((zone) => { - return `| ${zone} | ${date.setZone(zone).toFormat('EEE dd-MMM-yyyy HH:mm (hh:mm a)')} |` +]; %> + +## Date/Time + +| Timezone | Date/Time | +|----------|-----------| +<%= timezones.map((zone) => { + const zonedDate = date.toZonedDateTimeISO(zone) + const formatter = new Intl.DateTimeFormat('en-US', { + weekday: 'short', + month: 'short', + day: '2-digit', + year: 'numeric', + hour: '2-digit', + minute: '2-digit', + hour12: true, + timeZone: zone + }) + const formattedDate = formatter.format(new Date(zonedDate.epochMilliseconds)) + return `| ${zone} | ${formattedDate} |` }).join('\n') %> Or in your local time: -* https://www.timeanddate.com/worldclock/?iso=<%= date.toFormat("yyyy-MM-dd'T'HH:mm:ss") %> + +* https://www.timeanddate.com/worldclock/fixedtime.html?msg=<%= encodeURIComponent(title) %>&iso=<%= date.toZonedDateTimeISO('UTC').toPlainDateTime().toString().slice(0, 16).replace(/[-:]/g, '') %>&p1=1440&ah=1 ## Agenda @@ -31,17 +50,23 @@ Extracted from **<%= agendaLabel %>** labelled issues and pull requests from **< ## Invited -This meeting is open for anyone who wants to attend. Reminder to follow our [Code of Conduct](https://github.com/expressjs/express/blob/master/Code-Of-Conduct.md). +- @expressjs/express-tc +- @expressjs/triagers +- @expressjs/security-wg + +### Observers/Guests + +This meeting is open for anyone who wants to attend. Reminder to follow our [Code of Conduct](https://github.com/expressjs/.github/blob/master/CODE_OF_CONDUCT.md). -@expressjs/express-tc -@expressjs/triagers -@expressjs/security-wg +## Joining the meeting -## Links +* link for participants: <%= meetingLink %> -* Minutes: +--- -### Joining the meeting +Please use the following emoji reactions in this post to indicate your +availability. -* link for participants: https://zoom-lfx.platform.linuxfoundation.org/meeting/95266714809?password=f37cff1b-cb3a-4a21-9425-210e4714c72e -* For those who just want to watch: https://www.youtube.com/@expressjs-official +- 👍 - Attending +- 👎 - Not attending +- 😕 - Not sure yet diff --git a/.github/workflows/lintyMcLintface.yml b/.github/workflows/lintyMcLintface.yml new file mode 100644 index 0000000..ad1281f --- /dev/null +++ b/.github/workflows/lintyMcLintface.yml @@ -0,0 +1,15 @@ +name: 'Lint Markdown' + +on: [pull_request, push] + +permissions: + contents: read + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + - run: npm i + - run: npm test diff --git a/.github/workflows/meetings.yml b/.github/workflows/meetings.yml index 55e4113..319450c 100644 --- a/.github/workflows/meetings.yml +++ b/.github/workflows/meetings.yml @@ -1,40 +1,45 @@ name: Schedule Meetings on: + workflow_dispatch: pull_request: - push: - branches: - - master + paths: + - '.github/workflows/meetings.yml' + - '.github/ISSUE_TEMPLATE/meeting.md' schedule: - cron: '0 0 * * *' + +permissions: + issues: write + contents: read + jobs: meeting: runs-on: ubuntu-latest steps: - name: Technical Committee - uses: 'pkgjs/meet@v0' + uses: 'pkgjs/meet@v1' with: - issueTitle: '<%= date.toFormat("yyyy-MM-dd") %> Express TC Meeting' + issueTitle: '<%= date.toZonedDateTimeISO("UTC").toPlainDate().toString() %> Express TC Meeting' token: ${{ secrets.GITHUB_TOKEN }} orgs: expressjs,pillarjs,jshttp agendaLabel: 'tc agenda' meetingLabels: 'meeting' - # https://github.com/expressjs/discussions/issues/195#issuecomment-1973732769 - # Starting on 2024-03-18 at 8pm UTC (2024-03-18T21:00:00.0Z) with a period of 2 weeks (P2W) - schedules: '2024-03-18T20:00:00.0Z/P2W' + # Monday 1 PM America/Chicago with a period of 2 weeks (P2W) + schedules: '2025-08-04T13:00:00.0[America/Chicago]/P2W' createWithin: 'P1W' + meetingLink: 'https://zoom-lfx.platform.linuxfoundation.org/meeting/95266714809?password=f37cff1b-cb3a-4a21-9425-210e4714c72e' issueTemplate: 'meeting.md' - name: Working Session - uses: 'pkgjs/meet@v0' + uses: 'pkgjs/meet@v1' with: - issueTitle: '<%= date.toFormat("yyyy-MM-dd") %> Express Working Session' + issueTitle: '<%= date.toZonedDateTimeISO("UTC").toPlainDate().toString() %> Express Working Session' token: ${{ secrets.GITHUB_TOKEN }} orgs: expressjs,pillarjs,jshttp - agendaLabel: 'top priority, agenda' + agendaLabel: 'top priority' meetingLabels: 'meeting' - # Converting the second time slot to a "working session" - # https://github.com/expressjs/discussions/issues/195#issuecomment-1973732769 - # Starting on 2024-03-27 at 8pm UTC (2024-03-27T21:00:00.0Z) with a period of 2 weeks (P2W) - schedules: '2024-03-27T20:00:00.0Z/P2W' + # Wednesday 3 PM America/Chicago with a period of 2 weeks (P2W) + schedules: '2025-08-13T15:00:00.0[America/Chicago]/P2W' createWithin: 'P1W' + meetingLink: 'https://zoom-lfx.platform.linuxfoundation.org/meeting/95258037175?password=07aad89d-ff43-45df-9b28-f437e167a0b9' issueTemplate: 'meeting.md' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1170717 --- /dev/null +++ b/.gitignore @@ -0,0 +1,136 @@ +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# vuepress v2.x temp and cache directory +.temp +.cache + +# vitepress build output +**/.vitepress/dist + +# vitepress cache directory +**/.vitepress/cache + +# Docusaurus cache and generated files +.docusaurus + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..c36d90f --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,9 @@ +{ + "globs": [ + "**/*.md" + ], + "ignores": [ + ".github/**", + "node_modules/**" + ] +} \ No newline at end of file diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..dfb2e6c --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,11 @@ +# for reference, see https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml + +# Default state for all rules +default: true + +# MD013/line-length - Line length +MD013: false + +# MD033/no-inline-html - Inline HTML +MD033: + allowed_elements: ['kbd', 'sup'] diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..43c97e7 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +package-lock=false diff --git a/README.md b/README.md index d904f66..1bf99e2 100644 --- a/README.md +++ b/README.md @@ -15,3 +15,17 @@ of nature. Current meeting schedule: Wednesdays 23:30 UTC Recordings of past meetings are available on the [Express Youtube Channel](https://www.youtube.com/channel/UCYjxjAeH6TRik9Iwy5nXw7g/videos). + +### RFC vs ADR — The Real Difference + +An **RFC** is a *collaboration tool*: its purpose is to surface a problem, +explore solutions, gather feedback, and drive alignment. +It is iterative, often long-form, and meant for broad input. +An RFC does **not** imply a decision — it is a decision-making *process*. + +An **ADR** is a *recording tool*: its purpose is to capture a decision +that has already been made, including context, trade-offs, and consequences. +It is concise, stable, and part of the architectural history of a system. +An ADR does **not** create alignment — it preserves it. + +In essence: **RFC = how we decide**, **ADR = what we decided and why**. diff --git a/docs/CHARTER.md b/docs/CHARTER.md new file mode 100644 index 0000000..6836300 --- /dev/null +++ b/docs/CHARTER.md @@ -0,0 +1,92 @@ +# Express Charter + +## Section 0: Guiding Principles + +The Express project is part of the OpenJS Foundation which operates +transparently, openly, collaboratively, and ethically. +Project proposals, timelines, and status must not merely be open, but +also easily visible to outsiders. + +## Section 1: Scope + +Express is a HTTP web server framework with a simple and expressive API +which is highly aligned with Node.js core. We aim to be the best in +class for writing performant, spec compliant, and powerful web servers +in Node.js. As one of the oldest and most popular web frameworks in +the ecosystem, we have an important place for new users and experts +alike. + +### 1.1: In-scope + +Express is made of many modules spread between three GitHub Orgs: + +- [expressjs](https://github.com/expressjs/): Top level middleware and + libraries +- [pillarjs](https://github.com/pillarjs/): Components which make up + Express but can also be used for other web frameworks +- [jshttp](https://github.com/jshttp/): Low level HTTP libraries + +### 1.2: Out-of-Scope + +Section Intentionally Left Blank + +## Section 2: Relationship with OpenJS Foundation CPC + +Technical leadership for the projects within the OpenJS Foundation is +delegated to the projects through their project charters by the OpenJS +Cross Project Council (CPC). In the case of the Express project, it is +delegated to the Express Technical Committee ("TC"). + +This Technical Committee is in charge of both the day-to-day operations +of the project, as well as its technical management. This charter can +be amended by the TC requiring at least two approvals and a minimum two +week comment period for other TC members or CPC members to object. Any +changes the CPC wishes to propose will be considered a priority but +will follow the same process. + +### 2.1 Other Formal Project Relationships + +Section Intentionally Left Blank + +## Section 3: Express Governing Body + +The Express project is managed by the Technical Committee ("TC"). +Members can be added to the TC at any time. Any committer can nominate +another committer to the TC and the TC uses its standard consensus +seeking process to evaluate whether or not to add this new member. +Members who do not participate consistently at the level of a majority +of the other members are expected to resign. + +## Section 4: Roles & Responsibilities + +The Express TC manages all aspects of both the technical and community +parts of the project. Members of the TC should attend the regular +meetings when possible, and be available for discussion of time +sensitive or important issues. + +### Section 4.1 Project Operations & Management + +Section Intentionally Left Blank + +### Section 4.2: Decision-making, Voting, and/or Elections + +The Express TC uses a "consensus seeking" process for issues that are +escalated to the TC. The group tries to find a resolution that has no +open objections among TC members. If a consensus cannot be reached +that has no objections then a majority wins vote is called. It is also +expected that the majority of decisions made by the TC are via a +consensus seeking process and that voting is only used as a last-resort. + +Resolution may involve returning the issue to committers with +suggestions on how to move forward towards a consensus. It is not +expected that a meeting of the TC will resolve all issues on its +agenda during that meeting and may prefer to continue the discussion +happening among the committers. + +### Section 4.3: Other Project Roles + +Section Intentionally Left Blank + +## Section 5: Definitions + +Section Intentionally Left Blank diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md new file mode 100644 index 0000000..538ac01 --- /dev/null +++ b/docs/GOVERNANCE.md @@ -0,0 +1,205 @@ +# Express.js Community Contributing Guide 1.0 + +The goal of this document is to create a contribution process that: + +* Encourages new contributions. +* Encourages contributors to remain involved. +* Avoids unnecessary processes and bureaucracy whenever possible. +* Creates a transparent decision making process that makes it clear how +contributors can be involved in decision making. + +## Vocabulary + +* A **Contributor** is any individual creating or commenting on an issue or pull request. +* A **Committer** is a subset of contributors who have been given write access to the repository. +* A **Project Captain** is the lead maintainer of a repository. +* A **TC (Technical Committee)** is a group of committers representing the required technical +expertise to resolve rare disputes. +* A **Triager** is a subset of contributors who have been given triage access to the repository. + +## Logging Issues + +Log an issue for any question or problem you might have. When in doubt, log an issue, and +any additional policies about what to include will be provided in the responses. The only +exception is security disclosures which should be sent privately. + +Committers may direct you to another repository, ask for additional clarifications, and +add appropriate metadata before the issue is addressed. + +Please be courteous and respectful. Every participant is expected to follow the +project's Code of Conduct. + +## Contributions + +Any change to resources in this repository must be through pull requests. This applies to all changes +to documentation, code, binary files, etc. Even long term committers and TC members must use +pull requests. + +No pull request can be merged without being reviewed. + +For non-trivial contributions, pull requests should sit for at least 36 hours to ensure that +contributors in other timezones have time to review. Consideration should also be given to +weekends and other holiday periods to ensure active committers all have reasonable time to +become involved in the discussion and review process if they wish. + +The default for each contribution is that it is accepted once no committer has an objection. +During a review, committers may also request that a specific contributor who is most versed in a +particular area gives a "LGTM" before the PR can be merged. There is no additional "sign off" +process for contributions to land. Once all issues brought by committers are addressed it can +be landed by any committer. + +In the case of an objection being raised in a pull request by another committer, all involved +committers should seek to arrive at a consensus by way of addressing concerns being expressed +by discussion, compromise on the proposed change, or withdrawal of the proposed change. + +If a contribution is controversial and committers cannot agree about how to get it to land +or if it should land then it should be escalated to the TC. TC members should regularly +discuss pending contributions in order to find a resolution. It is expected that only a +small minority of issues be brought to the TC for resolution and that discussion and +compromise among committers be the default resolution mechanism. + +## Becoming a Triager + +Anyone can become a triager! Read more about the process of being a triager in +[the triage process document](contributing/triager-guide.md). + +Currently, any existing [organization member](https://github.com/orgs/expressjs/people) can nominate +a new triager. If you are interested in becoming a triager, our best advice is to actively participate +in the community by helping triaging issues and pull requests. As well we recommend +to engage in other community activities like attending the TC meetings, and participating in the Slack +discussions. If you feel ready and have been helping triage some issues, reach out to an active member of the organization to ask if they'd +be willing to support you. If they agree, they can create a pull request to formalize your nomination. In the case of an objection to the nomination, the triage team is responsible for working with the individuals involved and finding a resolution. + +You can also reach out to any of the [organization members](https://github.com/orgs/expressjs/people) +if you have questions or need guidance. + +## Becoming a Committer + +All contributors who have landed significant and valuable contributions should be onboarded in a timely manner, +and added as a committer, and be given write access to the repository. + +Committers are expected to follow this policy and continue to send pull requests, go through +proper review, and have other committers merge their pull requests. + +## TC Process + +The TC uses a "consensus seeking" process for issues that are escalated to the TC. +The group tries to find a resolution that has no open objections among TC members. +If a consensus cannot be reached that has no objections then a majority wins vote +is called. It is also expected that the majority of decisions made by the TC are via +a consensus seeking process and that voting is only used as a last-resort. + +Resolution may involve returning the issue to project captains with suggestions on +how to move forward towards a consensus. It is not expected that a meeting of the TC +will resolve all issues on its agenda during that meeting and may prefer to continue +the discussion happening among the project captains. + +Members can be added to the TC at any time. Any TC member can nominate another committer +to the TC and the TC uses its standard consensus seeking process to evaluate whether or +not to add this new member. The TC will consist of a minimum of 3 active members and a +maximum of 10. If the TC should drop below 5 members the active TC members should nominate +someone new. If a TC member is stepping down, they are encouraged (but not required) to +nominate someone to take their place. + +TC members will be added as admin's on the Github orgs, npm orgs, and other resources as +necessary to be effective in the role. + +To remain "active" a TC member should have participation within the last 12 months and miss +no more than six consecutive TC meetings. Our goal is to increase participation, not punish +people for any lack of participation, this guideline should be only be used as such +(replace an inactive member with a new active one, for example). Members who do not meet this +are expected to step down. If A TC member does not step down, an issue can be opened in the +discussions repo to move them to inactive status. TC members who step down or are removed due +to inactivity will be moved into inactive status. + +Inactive status members can become active members by self nomination if the TC is not already +larger than the maximum of 10. They will also be given preference if, while at max size, an +active member steps down. + +## Project Captains + +The Express TC can designate captains for individual projects/repos in the +organizations. These captains are responsible for being the primary +day-to-day maintainers of the repo on a technical and community front. +Repo captains are empowered with repo ownership and package publication rights. +When there are conflicts, especially on topics that effect the Express project +at large, captains are responsible to raise it up to the TC and drive +those conflicts to resolution. Captains are also responsible for making sure +community members follow the community guidelines, maintaining the repo +and the published package, as well as in providing user support. + +Like TC members, Repo captains are a subset of committers. + +To become a captain for a project the candidate is expected to participate in that +project for at least 6 months as a committer prior to the request. They should have +helped with code contributions as well as triaging issues. They are also required to +have 2FA enabled on both their GitHub and npm accounts. + +Any TC member or an existing captain on the **same** repo can nominate another committer +to the captain role. To do so, they should submit a PR to this document, updating the +**Active Project Captains** section (while maintaining the sort order) with the project +name, the nominee's GitHub handle, and their npm username (if different). + +* Repos can have as many captains as make sense for the scope of work. +* A TC member or an existing repo captain **on the same project** can nominate a new captain. + Repo captains from other projects should not nominate captains for a different project. + +The PR will require at least 2 approvals from TC members and 2 weeks hold time to allow +for comment and/or dissent. When the PR is merged, a TC member will add them to the +proper GitHub/npm groups. + +### Active Projects and Captains + +The list can be found at [https://github.com/expressjs/discussions/blob/HEAD/docs/contributing/captains_and_committers.md#active-projects-and-members](https://github.com/expressjs/discussions/blob/HEAD/docs/contributing/captains_and_committers.md#active-projects-and-members) + +### Current Initiative Captains + +The list can be found at [https://github.com/expressjs/discussions/blob/HEAD/docs/contributing/captains_and_committers.md#current-initiative-captains](https://github.com/expressjs/discussions/blob/HEAD/docs/contributing/captains_and_committers.md#current-initiative-captains) + +## Inactivity and Emeritus Policy for Any Role + +To support the health and continuity of the project, all individuals holding a role within the community (such as Triager, Committer, WG member, Project Captain, or TC member) are encouraged to maintain active participation. + +Inactivity is defined as the absence of meaningful involvement in the project—such as contributions, code reviews, triage, meeting attendance, or discussion participation—for a continuous period of 6 months. + +### Exceptions + +Anyone may request a temporary leave from active participation due to personal or professional reasons. In such cases, the individual should inform the relevant team or the Technical Committee (TC). During this time, the inactivity policy is paused, and the individual will not be flagged as inactive. + +### Inactivity Process + +* If someone is deemed inactive, the individual may be transitioned to an emeritus role that reflects their past contributions. A best effort will be made to inform them that this has occurred. They may request to be reinstated when they are ready to be active again. +* The emeritus status helps preserve a clear record of contributors who have meaningfully shaped the project over time. + +### Accountability + +* The Technical Committee (TC) and the respective captains of each package/team are responsible for assessing activity levels and enacting this policy fairly and transparently, in coordination with other relevant teams. +* In case of disagreement, the situation can be discussed and resolved by consensus within the TC or appropriate team. + +## Developer's Certificate of Origin 1.1 + +```text +By making a contribution 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/docs/LTS-strategy.md b/docs/LTS-strategy.md index da89f48..12d2fac 100644 --- a/docs/LTS-strategy.md +++ b/docs/LTS-strategy.md @@ -39,4 +39,4 @@ ### Release calendar -* There is a regular cadence of semver major releases (details TBD). However, if no breaking changes were introduced between the last semver major and the scheduled date of the release of the new one, the new semver major release is skipped. \ No newline at end of file +* There is a regular cadence of semver major releases (details TBD). However, if no breaking changes were introduced between the last semver major and the scheduled date of the release of the new one, the new semver major release is skipped. diff --git a/docs/adr/adr-template.md b/docs/adr/000-adr-template.md similarity index 98% rename from docs/adr/adr-template.md rename to docs/adr/000-adr-template.md index d06f6f9..da196bf 100644 --- a/docs/adr/adr-template.md +++ b/docs/adr/000-adr-template.md @@ -4,7 +4,7 @@ This is the base template that we use ```md -# ADR [Number]: [Title of Decision] +# ADR [PR Number]: [Title of Decision] ## Status diff --git a/docs/adr/290-using-caret-with-dependencies.md b/docs/adr/290-using-caret-with-dependencies.md new file mode 100644 index 0000000..06286f2 --- /dev/null +++ b/docs/adr/290-using-caret-with-dependencies.md @@ -0,0 +1,99 @@ +# ADR #290: Policy on Using Caret (`^`) or tilde (`~`) with Dependencies in `package.json` + +## Status + +Accepted + +## Submitters + +- Ulises Gascón (@UlisesGascon) + +## Decision Owners + +- Express TC (@expressjs/express-tc) + +## Context + +Historically, the Express project has avoided using the caret (`^`) in the `package.json` files for its own dependencies. This proposal aims to review whether this practice should continue or if adjustments are needed. + +**Why do we need this decision?** +Clarifying the policy on using caret (`^`) helps to ensure consistency across the Express ecosystem, reduce unnecessary maintenance, and prevent unexpected dependency updates. It also addresses concerns about the balance between keeping dependencies up-to-date and avoiding regressions. + +**What problem does it solve or avoid?** +This decision aims to reduce the maintenance burden of frequently updating pinned dependencies. + +**Are there any existing issues/discussions/pull requests related to this?** + +- [Discussion: Using caret (^) with our own dependencies #279](https://github.com/expressjs/discussions/issues/279) +- [expressjs/express#6017 (comment)](https://github.com/expressjs/express/issues/6017) + +## Decision + +We will adopt a policy where the caret (`^`) symbol is used for dependencies all dependencies. + +**What will be done?** + +- Update the `package.json` files to use `^` for all dependencies (both prod and dev). + +**Note on `^` vs. `~`:** + +- `^` allows updates to the most recent minor or patch version, offering greater flexibility and reducing the need for frequent manual updates. For example, `^1.2.3` will accept updates to `1.3.0`, `1.4.0`, but not `2.0.0`. +- `~` is more conservative, only allowing updates to patch versions. For example, `~1.2.3` will accept updates to `1.2.4`, `1.2.5`, but not `1.3.0`. Some Node.js legacy versions only support this, like Node@0.8. + +**What will not be done?** + +- We won't force to use `^` or `~` for any dependency if there is a reason to use a pinned version and it is properly documented. + +## Rationale + +**Alternatives Considered:** + +- **Alternative:** Continue pinning all dependencies, including internal ones, to specific versions. +- **Reason for rejection:** This approach requires frequent updates and increases the maintenance burden, as each minor or patch update requires a new release. + +**Pros and Cons**: + +**Pros**: + +- Reduces the number of PRs for updating our own dependencies. +- Allows for quicker adoption of minor and patch updates within the Express ecosystem. +- Users are still protected by lockfiles, mitigating the risk of regressions. + +**Cons**: + +- There is still a risk of minor regressions from updates, even within internally managed dependencies. +- Requires discipline in maintaining lockfiles to ensure stability for end users. + +**Why is this decision the best option?** +This decision strikes a balance between reducing maintenance effort and managing risk. It allows Express to leverage the benefits of semver for our own dependencies while maintaining control over external libraries that could introduce breaking changes. + +## Consequences + +**Positive Impact**: + +- Fewer manual updates required for internally managed dependencies. +- Users benefit from improvements and fixes in internal packages more quickly. + +**Negative Impact**: + +- Potential risk of regressions if an internal dependency introduces a breaking change in a minor update. +- Users relying on strict version control may need to adjust their expectations when using our own dependencies. + +**Mitigations**: + +- Strong test coverage and CI checks will help catch potential issues early. +- Clear communication in documentation and release notes to inform users of the updated dependency policy. +- Ensure that we are following strict semver when releasing our own libraries. + +## Implementation + +- **Phase 1**: Update `package.json` files across all packages to apply `^` for all dependencies which support greater than node@0.10.0. +- **Phase 2**: Review and adjust documentation to include the new policy on dependency versioning. + +## References + +- [NPM semver documentation](https://docs.npmjs.com/cli/v6/using-npm/semver) + +## Changelog + +- **[2024-10-22]**: @UlisesGascon - Initial draft of ADR for using caret (`^`) or tilde (`~`) with our own dependencies. diff --git a/docs/adr/funding-guidelines.md b/docs/adr/299-funding-guidelines.md similarity index 92% rename from docs/adr/funding-guidelines.md rename to docs/adr/299-funding-guidelines.md index 2c43854..96c1b89 100644 --- a/docs/adr/funding-guidelines.md +++ b/docs/adr/299-funding-guidelines.md @@ -1,14 +1,8 @@ ---- -name: Funding Use Guidelines -description: Guidelines for spending project funding -labels: ADR ---- - -# ADR [Number]: Funding Use Guidelines +# ADR #299: Funding Use Guidelines ## Status -Proposed +Accepted ## Submitters diff --git a/docs/adr/306-performance-wg.md b/docs/adr/306-performance-wg.md new file mode 100644 index 0000000..a6081b8 --- /dev/null +++ b/docs/adr/306-performance-wg.md @@ -0,0 +1,75 @@ +# ADR #306: Performance Working Group + +## Status + +Accepted + +## Submitters + +- @wesleytodd + +## Decision Owners + +- @expressjs/express-tc + +## Context + +Express has traditionally taken a very lax approach to performance. Historically this has meant poor outcomes with +and lack of visibility around how changes impact performance. The goal of this working +group is to centralize discussion so the whole ecosystem of packages can benefit from targeted performance work. The +scope of this WG would be all active packages in the `expressjs`, `pillarjs` and `jshttp` orgs with an initial focus on +the ones which are direct dependencies of `express` itself. + +**Why do we need a working group?** + +The current state is we have many open PRs, in flight initiatives, and planned future work. With a loose approach we +can easily have duplicated work, conflicting approaches, or focus on the wrong outcomes. By giving this WG scope over +this we can centralize the discussion and plans so that we unlock better and faster work in the individual packages. + +Additionally, there will be continued long term work to monitor and maintain the tooling. The WG structure gives a clear +place for users, contributors, and other interested parties to go so it is less difficult to find across the many org's +and repositories the project owns. + +## Decision + +Similar to the Security WG, we will setup a new repo (expressjs/perf-wg) and corresponding plan of action. The WG will +be delegated responsibility for driving concensus on initiatives within scope. This group will have three primary goals: + +1. Organize the effort. We want to make sure we are not rebuilding the same things or having the same disucssions in + many package repos at once. +2. Provide and maintain tooling for all the packages/repos to produce reliable performance metrics and benchmarks. + Examples include: workflows, infra and guidelines on types of benchmarks +3. Proritize and execute performance improvements across the packages. These do not need to be done *by* the members of + the WG, but it would be good if we could get reviews by the team we will setup to ensure folks with most experience + can help address performance issues across the project. + +We will need to take a few actions to get this started: + +1. Create a new `perf-wg` repo +2. Create teams: `@expressjs/perf-wg`, `@pillarjs/perf-wg`, `@jshttp/perf-wg` +3. Write charter/goals doc in the new repo +4. Schedule a recurring (monthly) meeting + +### Relation to STF + +Lastly, this kick-off work is being funded by the STF program. It is a part of our larger work around security +improvements for the project. There are two parts of that program which fall under this WG's purview: + +1. Milestone 6: Monitor performance across Express and direct dependencies + - Owner: @wesleytodd + - Delivery Date: Dec 31, 2025 + - Estimated Budget: €25,200 +1. Milestone 9: Improve performance for Express and critical dependencies + - Owner: @wesleytodd & @blakeembrey + - Delivery Date: Jun 30, 2026 + - Estimated Budget: €46,200 + +This funding does not mean the work can only be done by the owners, it just means that we are responsible for organizing +and executing on the deliverables. This is our first attempt at doing a program like this, so feedback is welcome. + +## References + +- +- +- open-telemetry/opentelemetry-js-contrib#2437 +- openjs-foundation/infrastructure#5 diff --git a/docs/adr/323-esm-support.md b/docs/adr/323-esm-support.md new file mode 100644 index 0000000..6c7c53f --- /dev/null +++ b/docs/adr/323-esm-support.md @@ -0,0 +1,92 @@ +# ADR: ESM exports + +## Status + +Accepted + +## Submitters + +- @kjugi +- @wesleytodd +- @ctcpip + +## Decision Owners + +- @expressjs/express-tc + +## Context + +The document's objective is to gather all notable comments and thoughts in one place and track potential changes in this topic. We have noticed that it is repeated frequently in many issues from the community and we need to take action. + +We have acknowledged the need and discussion around it touched on multiple scenarios. Including: + +- rethinking the process and exposing both options (ESM and CommonJS) for all libraries +- expose both options (ESM and CommonJS) for selected libraries +- maintaining status quo as the main target is on the server + +**Why do we need this decision?** +We aimed to consolidate the Technical Committee's (TC) opinion on this topic. It is important to emphasize that Express is an HTTP framework specifically designed for Node.js. Additionally, some of our libraries are being utilized by the community in other environments. + +**What problem does it solve or avoid?** +Ambiguity and uncertainty for the community, alongside clear guidance for repository maintainers and contributors. + +**Are there any existing issues/discussions/pull requests related to this?** + +- +- +- +- + +## Decision + +Holistically, as a project/team, we will not make a dedicated effort to export our libraries in the ESM format. + +This applies to all [expressjs](https://github.com/expressjs), [pillarjs](https://github.com/pillarjs), or [jshttp](https://github.com/jshttp) packages. + +**However, repo captains, as the primary maintainers of packages, retain autonomy and discretion of whether or not they choose to support ESM exports directly.** + +### What will be done? + +Future issues and PRs regarding ESM exports may be closed with a link to this document. + +## Rationale + +During the [working session](https://github.com/expressjs/discussions/issues/320), we had an in-depth discussion about this topic. + +This decision is motivated by the lack of resources to maintain such an effort in the long term. It is also worth noting that Express was specifically designed to run with Node.js. + +At present, our libraries function seamlessly in Node.js, supporting both CommonJS and ESM. Transitioning to support additional scenarios, such as direct ESM exports, would require significant changes to our CI systems and additional maintenance overhead. + +While the JavaScript ecosystem has increasingly moved toward ESM due to its compatibility with browsers, enhanced tree-shaking capabilities (coming from bundler tools), and support for dynamic imports, there are still complexities and challenges associated with ESM. + +Adopting ESM for our libraries would require a significant investment of time and resources to ensure proper implementation and long-term maintenance. While it is not impossible to achieve, it represents a considerable effort. Moreover, the majority of our users already utilize our libraries in their projects, relying on bundlers to handle the necessary transformations without issues. + +- **Alternatives Considered:** + - Add ESM export to our libraries. CommonJS format is accepted by bundlers. +- **Why is this decision the best option?** + - Time and energy can be shifted to other topics. + +## Consequences + +- **Positive Impact**: It does not require supporting another set of tools and major release. +- **Negative Impact**: + - No guarantee the packages work in browser environments. + - Potential community library fork (to make it ESM-friendly) might lack security updates over time + - OSS library authors that use our packages in ESM native libs might suffer from a lack of support +- **Mitigations**: Package maintainers may decide to expose both CJS and ESM + +## References + +Support for commonjs imports in ESM code is available in the node. Described in docs: + +- + +Support for ESM modules imports in commonjs is available in recent LTS Node.js versions. Docs: + +- + +## Changelog + +Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. + +- **[2025-01-15] - [2026-04-01]**: [@kjugi, @ctcpip, @wesleytodd] - initial doc diff --git a/docs/adr/352-lts-strategy.md b/docs/adr/352-lts-strategy.md new file mode 100644 index 0000000..7a447e3 --- /dev/null +++ b/docs/adr/352-lts-strategy.md @@ -0,0 +1,171 @@ +# ADR #352: LTS Strategy and Support Schedule + +## Status + +Accepted + +## Submitters + +- @wesleytodd + +## Decision Owners + +- @expressjs/express-tc + +## Context + +Conversation about our LTS strategy, support dates for our major release lines, and how we should message this content +has been spread out across multiple issues, repos, slack channels, and meetings. We have landed a few starter documents, +and generally have agreed on our goals/strategy but we have not officially documented and centralized that. This ADR is +both gathering all that context to one place as well as give concrete decisions and next steps. + +### Scope + +This ADR applies to, and should cover, all repositories within the Express Projects three orgs (`jshttp`, `pillarjs`, +`expressjs`). While everything stems from support for the primary `express` package, due to the coupling of many of our +dependency and middleware packages, we must also address those packages as well. + +### ADR Goals + +- Improve documentation on our support goals +- Document criteria and reasoning for when to release new majors +- Define life cycle for releases and terminology we will use +- Improve documentation on how our LTS relates to Node.js version support +- Documentation on how our LTS relates to our direct dependencies and other Express project repos/packages +- Set clear next steps for documenting and publicizing the LTS strategy +- Select dates for known release line support and EOL +- Create starter language and graphics for our future blog posts, website additions, and other necessary docs + +### ADR Non-Goals + +- Create an end-user documentation resource (either for immediate use or future use) +- Commit to future release dates + +**Existing issues/discussions/pull requests related to this:** + +- Initial LTS strategy doc: +- Additional LTS doc proposal: +- +- Some other related discussions: + - + - + - +- TC Slack Discussion: + +### Package/Repository Types + +We maintain four primary types of packages/repos: + +1. `express`: The minimal http framework +2. `express` dependencies: Libraries which are used directly or transitively within `express` and also by others outside + of the project +3. Middleware: Libraries for use *with* `express` but not installed with it directly +4. Others: Tools, documentation, websites, resources, etc. + +While much of this proposal is targeted specifically at `express`, this terminology will be used to differentiate where +we are not only talking about `express`. + +## Decision + +The Express project will have a well defined Long Term Support (LTS) strategy and schedule based on the following +requirements: + +- `express` major versions will go through three supported phases: Current, Active, & Maintenance + - `CURRENT`: A new major version is designated as `CURRENT` upon release. It is available but not the `latest` version + on npm for a minimum of 3 months. + - `ACTIVE`: After the minimum 3 month period and the TC agrees it is stable and secure, the `ACTIVE` version is + tagged `latest` on npm for a minimum of 12 months. + - `MAINTENANCE`: When a new major version becomes `ACTIVE`, the previous major version enters `MAINTENANCE` for a minimum of 12 months. +- After the `MAINTENANCE` time has ended the major version is considered `EOL` and is unsupported. +- During the `ACTIVE` period, a new major version may be released but *not* until at least 12 months have passed + since the `CURRENT` version became `ACTIVE`. +- Users are required to follow the head/latest of each major release line for support with all packages (`express`, + dependencies, middleware, & tools/other) +- If we have no necessary breaking changes, we will not release a new major version. Applies to `express`, + dependencies, middleware, & tools/other. +- Dropping old Node.js versions *alone* is not enough of a breaking change to release a new major version. Applies to + `express`, dependencies, middleware, & tools/other. +- `express` version 4.x is considered a special case. It will receive a longer `MAINTENANCE` phase of 18 months or until + the TC agrees we are safe cutting support. +- `express` dependency packages will follow the same timeline and support dates for the `express` version which they are + included with. +- Middleware packages should follow the timeline and support dates for the `express` versions they are compatible, but + should make reasonable and informed decisions which can deviate if necessary. +- All other packages are suggested to define an appropriate strategy for support. + +### Node.js Version Support + +While we recognize that runtime support needs to be tightly aligned with our LTS policy, it is out of scope for this +ADR and will be addressed in a separate proposal. + +### Life Cycle Phases & Meaning + +#### CURRENT + +- New majors will go through a short period of hardening to ensure stability, security, and ecosystem libraries/resources + compatibility. +- We will strive to ensure no breaking changes are included, but reserve the right to make security or high priority + fixes of breaking nature within this period. +- `CURRENT` lines will receive all types of active work including: bug fixes, security patches, new features, and + deprecation notices. +- Users are recommended to use `CURRENT` lines and to upgrade as quickly as their risk profile allows + +#### ACTIVE + +- `ACTIVE` lines will receive all types of active work including: bug fixes, security patches, new features, and + deprecation notices. +- For users, `ACTIVE` lines are considered the most stable and well supported version at any given time. + +#### MAINTENANCE + +- `MAINTENANCE` lines will only receive security patches or high priority bug fixes. +- Users are highly encouraged to upgrade to a `CURRENT` or `ACTIVE` release. + +### Schedule + +For the existing release lines, we will set the following phase dates: + +| Major | CURRENT | ACTIVE | MAINTENANCE | EOL | +| ----- | ------------------ | ---------- | ------------------ | ---------------------------------------- | +| 4.x | | | 2025-04-01 | no sooner than 2026-10-01 [1] | +| 5.x | 2024-09-11 | 2025-03-31 | TBD [2] | TBD [2] | +| 6.x | TBD [3] | | | | + +1. v4 is a special case, and we may extend MAINTENANCE support. This date is called out to give users confidence we will + not end-of-life *earlier* than this date. +2. v5 MAINTENANCE and EOL dates are determined by when v6 is released. We will update them when v6 release dates are + committed to. +3. v6 work has not started yet. The earliest we could choose to release by this proposal is 2026-01-01. We will update + these dates when we commit to them. + +### Documentation + +The project will maintain two types of documentation for this: + +#### Project documentation for the maintainers + +This includes this doc, but also detailed things about the process that are not necessary for anyone but us. This +documentation will live in one of two places: + +1. The `discussions` repo. If the content applies to more than one repo/package in any of the three orgs, is general in + nature, or otherwise has no logical other place to go it goes here. +2. The individual repo/package to which it applies. If an individual package has more detailed or different needs the + docs will live along with the repo as decided by the captains. + +#### User documentation + +This will be produced for the website. While the source content of it may live in other places (for example a repo to +produce an image for the schedule), the users will be directed to the website to view the current updated version. This +will also co-locate with documentation about Node.js support and other related support content. + +#### Next steps + +- Update the existing LTS doc with more details from this decision +- Update website pages with more details from this decision +- Close out discussions and other PRs related to this + +## Changelog + +Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. + +- **[2025-02-28]**: [@wesleytodd] - Initial draft diff --git a/docs/adr/366-action-pinning.md b/docs/adr/366-action-pinning.md new file mode 100644 index 0000000..bb0c1cb --- /dev/null +++ b/docs/adr/366-action-pinning.md @@ -0,0 +1,61 @@ +# ADR 366: GitHub Actions - to pin or not to pin + +## Status + +Accepted + +## Submitters + +- @ctcpip + +## Decision Owners + +- @expressjs/express-tc + +## Context + +GitHub Actions support referencing actions via: + +- Semantic versions (e.g., `actions/setup-node@v4`) +- Specific commit hashes (e.g., `actions/setup-node@49933ea`) +- Branch references (e.g., `actions/setup-node@main`) + +Tools like [OpenSSF Scorecard](https://github.com/ossf/scorecard) recommend pinning to commit hashes to guarantee supply chain integrity and reduce the risk of malicious updates. However, GitHub's own documentation states: + +> "All options are a tradeoff between guaranteed supply chain integrity and auto-patching of vulnerabilities in dependencies." + +Therefore, there is no perfect solution; only pros and cons depending on which choice is made. + +A recent discussion raised valid concerns about the real-world security value of pinning, particularly: + +- **Pinning disables automatic updates**, including security patches, unless maintained manually. +- **Commit hashes are opaque**, harder to audit, and easy to misuse (e.g., referencing a malicious fork). +- **Most CI workflows in our repos don't access secrets**, minimizing risk even in the event of compromise. + +Additionally, human verification of pinned commits, especially across many repos, can be error-prone or inconsistent. + +## Decision + +We will **not require pinning GitHub Actions to commit hashes** across all repositories. + +Instead: + +- Use **semantic version tags** (e.g., `@v4`) by default. +- Do **not use `@main` or other floating branch refs**. +- Repositories should **enable Dependabot for GitHub Actions** and set `schedule/interval` to a reasonable value, such as `monthly`. +- For workflows that **access secrets, publish artifacts, or have privileged scopes**, repository maintainers **may** choose to pin to commit hashes **if justified**. +- Where pinning is used: + - A reviewer **must manually verify** the commit hash belongs to the correct source repository. + - The verification step **must be noted in the PR review** to ensure accountability. + +## Consequences + +- **Improved maintainability**: Semantic versions reduce the burden of keeping commit hashes up to date. +- **Timely security updates**: Using version tags with Dependabot allows faster adoption of upstream patches. +- **Acknowledged risk**: While this approach reduces supply chain guarantees, the practical risk profile of most of our workflows does not justify the burden of pinning. +- **Flexibility for maintainers**: Projects/workflows with higher sensitivity can still opt into pinning where warranted. + +## References + +- [Keeping your GitHub Actions and workflows secure](https://securitylab.github.com/resources/github-actions-building-blocks/) +- [Mitigating Attack Vectors in GitHub Workflows](https://openssf.org/blog/2024/08/12/mitigating-attack-vectors-in-github-workflows/) diff --git a/docs/adr/adr-xxx-adoption-of-ossf-scorecard-for-express.md b/docs/adr/adr-xxx-adoption-of-ossf-scorecard-for-express.md new file mode 100644 index 0000000..538b204 --- /dev/null +++ b/docs/adr/adr-xxx-adoption-of-ossf-scorecard-for-express.md @@ -0,0 +1,72 @@ +# ADR 83381fbd-593e-49c6-9419-1fe569ac89aa: Adoption of OSSF Scorecard for Express + +## Status + +Proposed + +## Submitters + +- @ulisesgascon +- @carpasse +- @inigomarquinez + +## Decision Owners + +- @expressjs/security-wg +- @expressjs/tc + +## Context + +The Open Source Security Foundation (OSSF) Scorecards project generates an automated "security score" for open source projects. This score aids users in assessing the security posture, risk level, and trustworthiness of a project, providing a standardized measure for comparing projects and making informed decisions when adopting new open-source dependencies. The scorecards can also facilitate automated decision-making processes for organizations, as new dependencies can be flagged for further evaluation if they fall below a specified security score threshold. This approach reduces the risk of malicious dependencies infiltrating production systems—a risk highlighted by recent incidents involving malicious NPM packages. + +The Node.js organization has successfully implemented OSSF Scorecard monitoring, leading to notable security improvements across several repositories. Following this model, we propose adopting a similar approach for the Express framework. Tools like the OpenSSF Scorecard Monitor and Visualizer, along with established processes, make ongoing score management manageable and effective, providing straightforward ways to monitor and improve project security scores. + +## Decision + +The Express project will adopt OSSF Scorecard reporting as part of its security assessment and improvement practices. + +### Actions + +- Integrate OSSF Scorecards and establish monitoring through GitHub Actions with the OpenSSF Scorecard Monitor. +- Track actionable items highlighted by the Scorecard in individual PRs, which will detail specific security improvements. +- Engage contributors, including new collaborators, by involving them in the creation and review of Scorecard-related PRs. + +### Exclusions + +- Some suggestions made by the Scorecard may not be implemented in the organization for various reasons. For example, we decided that [pinning dependencies is considered optional](https://github.com/expressjs/discussions/blob/master/docs/adr/366-action-pinning.md). It is important to reach consensus before making bulk changes across repositories. + +## Rationale + +The decision to adopt OSSF Scorecards stems from its demonstrated impact in similar environments, such as the Node.js project, where it has proven valuable for continuous security improvement and community engagement. Key considerations include: + +- **Alternatives Considered:** + - **Manual Security Audits**: Resource-intensive and lacks the automated frequency and granularity provided by Scorecards. + +- **Pros and Cons**: + - **Pros**: Provides automated, actionable insights; strengthens security posture; enables community involvement in a structured way; widely recognized within open source communities. + - **Cons**: Initial setup and monitoring require dedicated resources; minor learning curve for contributors unfamiliar with the process. + +The OSSF Scorecard is a mature, well-supported solution that aligns with Express's commitment to security and community engagement, making it the most fitting choice. + +## Consequences + +- **Positive Impact**: The OSSF Scorecard will contribute to Express's security posture by providing clear, actionable insights and facilitating ongoing improvement. It will also streamline the involvement of new collaborators, providing a welcoming entry point into Express contributions. +- **Negative Impact**: The Scorecard’s regular updates may require ongoing maintenance, and individual PR reviews could increase workload initially. Additionally, the Express organization has a large number of repositories, meaning each will require separate Scorecard implementation and upkeep until a centralized solution is found, increasing the management burden. +- **Mitigations**: Regular reviews in Security WG meetings, ongoing monitoring of scoring trends, and continued engagement with the triage team will help manage these challenges. We are also exploring the possibility of a centralized tool to streamline OSSF Scorecard implementation across all repositories, which could significantly reduce maintenance efforts. + +## Implementation + +- Already implemented across the three GitHub organizations related to the Express ecosystem: [expressjs](https://github.com/expressjs), [pillarjs](https://github.com/pillarjs), and [jshttp](https://github.com/jshttp). +- The security team will monitor changes in the Scorecard results and address issues as needed. The team will determine what can be fixed and prioritize accordingly. To streamline this process, an [automation is in place](https://github.com/expressjs/security-wg/blob/main/.github/workflows/ossf-scorecard-reporting.yml) that reports changes in the Scorecard scores. + +## References + +- [OSSF Scorecards documentation](https://securityscorecards.dev/) +- [OpenSSF Scorecards project announcement](https://openssf.org/blog/2020/11/06/security-scorecards-for-open-source-projects/) +- [PR to add support for OSSF scorecard reporting in Express](https://github.com/expressjs/express/pull/5431) +- [PR to add OSSF scorecard in Node.js](https://github.com/nodejs/security-wg/issues/851) +- [Scorecards API for results](https://api.securityscorecards.dev/#/results) + +## Changelog + +- **[2024-10-30]**: @inigomarquinez - Drafted and proposed ADR for the adoption of OSSF Scorecard for Express. diff --git a/docs/adr/typescript-wg.md b/docs/adr/typescript-wg.md new file mode 100644 index 0000000..3b867d5 --- /dev/null +++ b/docs/adr/typescript-wg.md @@ -0,0 +1,71 @@ +# ADR #005: TypeScript Working Group + +## Status + +Proposed + +## Submitters + +- @bjohansebas + +## Decision Owners + +- @expressjs/express-tc + +## Context + +TypeScript is now widely adopted and has a large, active community. Many developers use it alongside packages maintained by the Express project. As such, there's a growing need to enhance TypeScript support — both by maintaining accurate type definitions and by addressing existing and future issues related to typings. + +- **Why do we need this decision?** + +As the Express project continues to evolve, we want to improve our engagement with the community. Having a dedicated group focused on TypeScript-related matters will enhance our support, especially since not all maintainers are familiar with TypeScript. An active working group will help manage and resolve type-related issues effectively. + +- **What problem does it solve or avoid?** + +This proposal aims to establish a dedicated team responsible for maintaining TypeScript types, whether in DefinitelyTyped or directly within the repositories. It will also help triage and resolve the numerous issues reported daily related to type definitions. + +- **Are there any existing issues/discussions/pull requests related to this?**: + + - + - + +## Decision + +Similar to the Security WG and Performance WG, we will set up a new repository (expressjs/typescript-wg) along with a corresponding action plan. This working group will be empowered to build consensus and make decisions within its scope. Its core responsibilities will include: + +- Ensure `express` package types are semantically correct, current with the implementation, and provide a high-quality developer experience +- Making decisions on TypeScript support within Express-maintained repositories +- Maintaining up-to-date TypeScript type definitions +- Enhancing documentation for TypeScript usage across Express packages +- Support testing type accuracy while in development and CI +- Ensure that types shared across Express Project packages are updated in sync to prevent build errors across the ecosystem + +### Initial Goal + +The TypeScript Working Group’s initial goal is to ensure that the `express` package has **high-quality, semantically correct, and up-to-date type definitions that accurately reflect its public API.** + +As part of this effort, the working group will also evaluate whether and how to support types in other Express-maintained packages. Decisions around publishing first party types vs. DefinitelyTyped maintenance, release cycle alignment, and tooling support will be developed collaboratively and documented as part of the group's ongoing charter. +We will need to take a few actions to get this started: + +1. Create a new `typescript-wg` repo +2. Create teams: `@expressjs/typescript-wg`, `@pillarjs/typescript-wg`, `@jshttp/typescript-wg` +3. Write charter/goals doc in the new repo + +## Rationale + +Since Express has become active again and the new version, Express v5, has been released, several issues related to typings have emerged. There have also been discussions about actively integrating type definitions within the repositories. + +Most packages under the Express umbrella are not written in TypeScript, and not all maintainers are interested in taking on type maintenance responsibilities. A small number (such as `path-to-regexp`) maintain their own types, but this is the exception rather than the norm. + +The proposed working group provides a focused avenue for contributors who are interested in TypeScript to collaboratively improve, maintain, and guide the strategy for type definitions across Express projects, starting with the core `express` package. + +## References + +- +- + +## Changelog + +Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. + +- **[2025-05-28]**: [@bjohansebas] - Initial draft diff --git a/docs/contributing/captains_and_committers.md b/docs/contributing/captains_and_committers.md new file mode 100644 index 0000000..45739f2 --- /dev/null +++ b/docs/contributing/captains_and_committers.md @@ -0,0 +1,111 @@ +# Active projects and members + +- [`expressjs/badgeboard`](https://github.com/expressjs/badgeboard): @wesleytodd +- [`expressjs/basic-auth-connect`](https://github.com/expressjs/basic-auth-connect): @ulisesGascon +- [`expressjs/body-parser`](https://github.com/expressjs/body-parser): + - Captains: @jonchurch, @ulisesGascon + - Committers: @Phillip9587 +- [`expressjs/codemod`](https://github.com/expressjs/codemod): + - captains: @bjohansebas, @kjugi + - committers: @AugustinMauroy +- [`expressjs/compression`](https://github.com/expressjs/compression): + - captains: @UlisesGascon + - committers: @bjohansebas +- [`expressjs/cookie-parser`](https://github.com/expressjs/cookie-parser): @wesleytodd, @UlisesGascon +- [`expressjs/cookie-session`](https://github.com/expressjs/cookie-session): @ulisesGascon +- [`expressjs/cors`](https://github.com/expressjs/cors): @jonchurch, @ulisesGascon +- [`expressjs/discussions`](https://github.com/expressjs/discussions): @wesleytodd +- [`expressjs/errorhandler`](https://github.com/expressjs/errorhandler): @ulisesGascon +- [`expressjs/express`](https://github.com/expressjs/express): + - captains: @wesleytodd, @ulisesGascon + - committers: @bjohansebas, @Phillip9587 +- [`expressjs/expressjs.com`](https://github.com/expressjs/expressjs.com): + - captains: @crandmck, @jonchurch, @bjohansebas + - committers: @carlosstenzel @ShubhamOulkar +- [`expressjs/generator`](https://github.com/expressjs/generator): @wesleytodd +- [`expressjs/method-override`](https://github.com/expressjs/method-override): @ulisesGascon +- [`expressjs/morgan`](https://github.com/expressjs/morgan): @jonchurch, @ulisesGascon +- [`expressjs/multer`](https://github.com/expressjs/multer): @LinusU, @ulisesGascon +- [`expressjs/response-time`](https://github.com/expressjs/response-time): + - Captains: @ulisesGascon + - Committers: @carpasse +- [`expressjs/serve-favicon`](https://github.com/expressjs/serve-favicon): @ulisesGascon +- [`expressjs/serve-index`](https://github.com/expressjs/serve-index): @ulisesGascon +- [`expressjs/serve-static`](https://github.com/expressjs/serve-static): @ulisesGascon +- [`expressjs/session`](https://github.com/expressjs/session): + - Captains: @ulisesGascon + - Committers: @bjohansebas +- [`expressjs/statusboard`](https://github.com/expressjs/statusboard): @wesleytodd +- [`expressjs/timeout`](https://github.com/expressjs/timeout): @ulisesGascon +- [`expressjs/vhost`](https://github.com/expressjs/vhost): @ulisesGascon +- [`jshttp/accepts`](https://github.com/jshttp/accepts): @blakeembrey +- [`jshttp/basic-auth`](https://github.com/jshttp/basic-auth): @blakeembrey +- [`jshttp/compressible`](https://github.com/jshttp/compressible): @blakeembrey +- [`jshttp/content-disposition`](https://github.com/jshttp/content-disposition): @blakeembrey +- [`jshttp/content-type`](https://github.com/jshttp/content-type): @blakeembrey +- [`jshttp/cookie`](https://github.com/jshttp/cookie): @blakeembrey +- [`jshttp/etag`](https://github.com/jshttp/etag): @blakeembrey +- [`jshttp/forwarded`](https://github.com/jshttp/forwarded): @blakeembrey +- [`jshttp/fresh`](https://github.com/jshttp/fresh): @blakeembrey +- [`jshttp/http-assert`](https://github.com/jshttp/http-assert): @wesleytodd, @jonchurch, @ulisesGascon +- [`jshttp/http-errors`](https://github.com/jshttp/http-errors): @wesleytodd, @jonchurch, @ulisesGascon +- [`jshttp/media-typer`](https://github.com/jshttp/media-typer): @blakeembrey +- [`jshttp/methods`](https://github.com/jshttp/methods): @blakeembrey +- [`jshttp/mime-db`](https://github.com/jshttp/mime-db): @blakeembrey, @UlisesGascon +- [`jshttp/mime-types`](https://github.com/jshttp/mime-types): @blakeembrey, @UlisesGascon +- [`jshttp/negotiator`](https://github.com/jshttp/negotiator): @blakeembrey +- [`jshttp/on-finished`](https://github.com/jshttp/on-finished): + - Captains: @wesleytodd, @ulisesGascon + - Committers: @Phillip9587 +- [`jshttp/on-headers`](https://github.com/jshttp/on-headers): @blakeembrey +- [`jshttp/proxy-addr`](https://github.com/jshttp/proxy-addr): @wesleytodd, @ulisesGascon +- [`jshttp/range-parser`](https://github.com/jshttp/range-parser): @blakeembrey +- [`jshttp/statuses`](https://github.com/jshttp/statuses): @blakeembrey +- [`jshttp/type-is`](https://github.com/jshttp/type-is): @blakeembrey +- [`jshttp/vary`](https://github.com/jshttp/vary): @blakeembrey +- [`pillarjs/cookies`](https://github.com/pillarjs/cookies): @blakeembrey +- [`pillarjs/csrf`](https://github.com/pillarjs/csrf): @ulisesGascon +- [`pillarjs/encodeurl`](https://github.com/pillarjs/encodeurl): @blakeembrey +- [`pillarjs/finalhandler`](https://github.com/pillarjs/finalhandler): + - captains: @wesleytodd, @ulisesGascon + - committers: @Phillip9587 +- [`pillarjs/hbs`](https://github.com/pillarjs/hbs): @ulisesGascon +- [`pillarjs/multiparty`](https://github.com/pillarjs/multiparty): @blakeembrey +- [`pillarjs/iconv-lite`](https://github.com/pillarjs/iconv-lite): + - Captains: @ashtuchkin, @bjohansebas + - Committers: @Phillip9587 +- [`pillarjs/parseurl`](https://github.com/pillarjs/parseurl): @blakeembrey +- [`pillarjs/path-to-regexp`](https://github.com/pillarjs/path-to-regexp): @blakeembrey +- [`pillarjs/request`](https://github.com/pillarjs/request): @wesleytodd +- [`pillarjs/resolve-path`](https://github.com/pillarjs/resolve-path): @blakeembrey +- [`pillarjs/router`](https://github.com/pillarjs/router): @wesleytodd, @ulisesGascon +- [`pillarjs/send`](https://github.com/pillarjs/send): @blakeembrey +- [`pillarjs/understanding-csrf`](https://github.com/pillarjs/understanding-csrf): @ulisesGascon + +## Current Initiative Captains + +- [Triage team](https://github.com/expressjs/discussions/issues/227): @UlisesGascon, @bjohansebas +- [Security WG](https://github.com/expressjs/security-wg): @UlisesGascon +- [Perf WG](https://github.com/expressjs/perf-wg): @wesleytodd +- [Typescript WG](https://github.com/expressjs/typescript-wg): @jonchurch, @bjohansebas +- Archived repos and deprecated packages: @UlisesGascon + +## Accounts details + +- @ashtuchkin (npm: [~ashtuchkin](https://www.npmjs.com/~ashtuchkin)) +- @bjohansebas (npm: [~bsebas](https://www.npmjs.com/~bsebas)) +- @blakeembrey (npm: [~blakeembrey](https://www.npmjs.com/~blakeembrey)) +- @crandmck (npm: [~crandmck](https://www.npmjs.com/~crandmck)) +- @ctcpip (npm: [~ctcpip](https://www.npmjs.com/~ctcpip)) +- @jonchurch (npm: [~jonchurch](https://www.npmjs.com/~jonchurch)) +- @kjugi (npm: [~filip.kudla](https://www.npmjs.com/~filip.kudla)) +- @LinusU (npm: [~linusu](https://www.npmjs.com/~linusu)) +- @seplu (npm: [~sheplu](https://www.npmjs.com/~sheplu)) +- @ulisesGascon (npm: [~ulisesgascon](https://www.npmjs.com/~ulisesgascon)) +- @wesleytodd (npm: [~wesleytodd](https://www.npmjs.com/~wesleytodd)) + +## Emeritus Members + +- [`expressjs/expressjs.com`](https://github.com/expressjs/expressjs.com): + - triage: @juliogarciape @inigomarquinez + - committers: @chrisdel101 diff --git a/docs/contributing/readme-guide.md b/docs/contributing/readme-guide.md new file mode 100644 index 0000000..6e3d637 --- /dev/null +++ b/docs/contributing/readme-guide.md @@ -0,0 +1,124 @@ +# README guidelines + +Every module in the expressjs, pillarjs, and jshttp organizations should have +a README file named `README.md`. The purpose of the README is to: + +- Explain the purpose of the module and how to use it. +- Act as a landing page (both on GitHub and npmjs.com) for the module to help + people find it via search. Middleware module READMEs are also incorporated + into . +- Encourage community contributions and participation. + +Use the [README template](https://github.com/expressjs/express/wiki/README-template) +to quickly create a new README file. + +## Top-level items + +**Badges** (optional): At the very top (with no subheading), include any +applicable badges, such as npm version/downloads, build status, test coverage, +and so on. Badges should resolve properly (not display a broken image). + +Possible badges include: + +- npm version: `[![NPM Version][npm-image]][npm-url]` +- npm downloads: `[![NPM Downloads][downloads-image]][downloads-url]` +- test coverage: `[![Test Coverage][coveralls-image]][coveralls-url]` + +**Summary**: Following badges, provide a one- or two-sentence description of +what the module does. This should be the same as the npmjs.org blurb (which +comes from the description property of `package.json`). Since npm doesn't +handle markdown for the blurb, avoid using markdown in the summary sentence. + +**TOC** (Optional): For longer READMEs, provide a table of contents that has +a relative link to each section. A tool such as +[doctoc](https://www.npmjs.com/package/doctoc) makes it very easy to generate +a TOC. + +## Overview + +Optionally, include a section of one or two paragraphs with more high-level +information on what the module does, what problems it solves, why one would +use it and how. Don't just repeat what's in the summary. + +## Installation + +Required. This section is typically just: + +```sh +npm install module-name +``` + +But include any other steps or requirements. + +NOTE: Use the `sh` code block to make the shell command display properly on +the website. + +## Basic use + +- Provide a general description of how to use the module with code sample. + Include any important caveats or restrictions. +- Explain the most common use cases. +- Optional: a simple "hello world" type example (where applicable). This + example is in addition to the more comprehensive [example section](#examples) + later. + +## API + +Provide complete API documentation. + +Formatting conventions: Each function is listed in a 3rd-level heading (`###`), +like this: + +```js +### functionName(arg, options [, optional_arg] ... ) +``` + +### Options objects + +For arguments that are objects (for example, options object), describe the +properties in a table, as follows. This matches the formatting used in the +[Express API docs](https://expressjs.com/en/4x/api.html). + +|Property | Description | Type | Default| +|----------|-----------|------------|-------------| +|Name of the property in `monospace`. | Brief description | String, Number, Boolean, etc. | If applicable.| + +If all the properties are required (i.e. there are no defaults), then you +can omit the default column. + +Instead of very lengthy descriptions, link out to subsequent paragraphs for +more detailed explanation of specific cases (e.g. "When this property is set +to 'foobar', xyz happens; see <link to following section >.) + +If there are options properties that are themselves options, use additional +tables. See [`trust proxy` and `etag` properties](https://expressjs.com/en/4x/api.html#app.settings.table). + +## Examples + +Every README should have at least one example; ideally more. For code samples, +be sure to use the `js` code block, for proper display in the website, e.g.: + +```js +var csurf = require('csurf') +... +``` + +## Tests + +What tests are included. + +How to run them. + +The convention for running tests is `npm test`. All our projects should follow +this convention. + +## Contributors + +Names of module "owners" (lead developers) and other developers who have +contributed. + +## License + +Link to the license, with a short description of what it is, e.g. "MIT" or +whatever. Ideally, avoid putting the license text directly in the README; link +to it instead. diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md new file mode 100644 index 0000000..87dd20b --- /dev/null +++ b/docs/contributing/release-process.md @@ -0,0 +1,203 @@ +# Express Release Process + +This document contains the technical aspects of the Express release process. The +intended audience is those who have been authorized by the Express Technical +Committee (TC) to create, promote and sign official release builds for any +package governed by Express. + +## Who can make releases? + +According to project governance, only package Captains or members of the Technical +Committee (TC) are permitted to make releases. Captains have the freedom to make releases +for their own package whenever necessary, while TC members may make releases for any package +as needed. + +### 1. Github release access + +The person making the release must be either the package captain or a member of the TC in +order to have sufficient permissions to do the work. + +### 2. npmjs.com release access + +The individual making the release will need to be made an owner on the +package on npmjs.com so they are able to publish the release +(see Step 6). + +## How to publish a release + +Before publishing, the following preconditions should be met: + +- A release proposal issue or tracking pull request (see "Proposal branch" + below) will exist documenting: + - the proposed changes + - the type of release: patch, minor or major + - the version number (according to semantic versioning - ) +- The proposed changes should be complete. + +There are two main release flows: patch and non-patch. + +The patch flow is for making **patch releases**. As per semantic versioning, +patch releases are for simple changes, eg: typo fixes, patch dependency updates, +and simple/low-risk bug fixes. Every other type of change is made via the +non-patch flow. + +### Branch terminology + +"Master branch" + +- There is a branch in git used for the current major version of Express, named + `master`. +- This branch contains the completed commits for the next patch release of the + current major version. +- Releases for the current major version are published from this branch. + +"Version branch" + +- For any given major version of Express (current, previous or next) there is + a branch in git for that release named `.x` (eg: `4.x`). +- This branch points to the commit of the latest tag for the given major version. + +"Release branch" + +- For any given major version of Express, there is a branch used for publishing + releases. +- For the current major version of Express, the release branch is the + "Master branch" named `master`. +- For all other major versions of Express, the release branch is the + "Version branch" named `.x`. + +"Proposal branch" + +- A branch in git representing a proposed new release of Express. This can be a + minor or major release, named `.0` for a major release, + `.` for a minor release. +- A tracking pull request should exist to document the proposed release, + targeted at the appropriate release branch. Prior to opening the tracking + pull request the content of the release may have be discussed in an issue. +- This branch contains the commits accepted so far that implement the proposal + in the tracking pull request. + +### Pre-release Versions + +Alpha and Beta releases are made from a proposal branch. The version number should be +incremented to the next minor version with a `-beta` or `-alpha` suffix. +For example, if the next beta release is `5.0.1`, the beta release would be `5.0.1-beta.0`. +The pre-releases are unstable and not suitable for production use. + +### Patch flow + +In the patch flow, simple changes are committed to the release branch which +acts as an ever-present branch for the next patch release of the associated +major version of Express. + +The release branch is usually kept in a state where it is ready to release. +Releases are made when sufficient time or change has been made to warrant it. +This is usually proposed and decided using a github issue. + +### Non-patch flow + +In the non-patch flow, changes are committed to a temporary proposal branch +created specifically for that release proposal. The branch is based on the +most recent release of the major version of Express that the release targets. + +Releases are made when all the changes on a proposal branch are complete and +approved. This is done by merging the proposal branch into the release branch +(using a fast-forward merge), tagging it with the new version number and +publishing the release package to npmjs.com. + +### Flow + +Below is a detailed description of the steps to publish a release. + +#### Step 1. Check the release is ready to publish + +Check any relevant information to ensure the release is ready, eg: any +milestone, label, issue or tracking pull request for the release. The release +is ready when all proposed code, tests and documentation updates are complete +(either merged, closed or re-targeted to another release). + +#### Step 2. (Non-patch flow only) Merge the proposal branch into the release branch + +In the patch flow: skip this step. + +In the non-patch flow: + +```sh +git checkout +git merge --ff-only +``` + +`` - see "Release branch" of "Branches" above. +`` - see "Proposal branch" of "Non-patch flow" above. + +> [!NOTE] +> You may need to rebase the proposal branch to allow a fast-forward +> merge. Using a fast-forward merge keeps the history clean as it does +> not introduce merge commits. + +### Step 3. Update the History.md and package.json to the new version number + +The changes so far for the release should already be documented under the +"unreleased" section at the top of the History.md file, as per the usual +development practice. Change "unreleased" to the new release version / date. +Example diff fragment: + +```diff +-unreleased +-========== ++4.13.3 / 2015-08-02 ++=================== +``` + +The version property in the package.json should already contain the version of +the previous release. Change it to the new release version. + +Commit these changes together under a single commit with the message set to +the new release version (eg: `4.13.3`): + +```sh +$ git checkout +<..edit files..> +$ git add History.md package.json +$ git commit -m '' +``` + +### Step 4. Identify and tag the release commit with the new release version + +Create a lightweight tag (rather than an annotated tag) named after the new +release version (eg: `4.13.3`). + +```sh +git tag +``` + +### Step 5. Push the release branch changes and tag to github + +The branch and tag should be pushed directly to the main repository +(). + +```sh +git push origin +git push origin +``` + +### Step 6. Publish to npmjs.com + +Ensure your local working copy is completely clean (no extra or changed files). +You can use `git status` for this purpose. + +```sh +npm login +npm publish +``` + +> [!NOTE] +> The version number to publish will be picked up automatically from +> package.json. + +### Step 7. Update documentation website + +The documentation website documents the current release version in various places. To update these, follow these steps: + +1. Manually run the [`Update External Docs` workflow](https://github.com/expressjs/expressjs.com/actions/workflows/update-external-docs.yml) in expressjs.com repository. +2. Add a new section to the [changelog](https://github.com/expressjs/expressjs.com/blob/gh-pages/en/changelog/index.md) in the expressjs.com website. diff --git a/docs/contributing/triager-guide.md b/docs/contributing/triager-guide.md new file mode 100644 index 0000000..051f873 --- /dev/null +++ b/docs/contributing/triager-guide.md @@ -0,0 +1,72 @@ +# Express Triager Guide + +## Issue Triage Process + +When a new issue or pull request is opened the issue will be labeled with `needs triage`. +If a triage team member is available they can help make sure all the required information +is provided. Depending on the issue or PR there are several next labels they can add for further +classification: + +* `needs triage`: This can be kept if the triager is unsure which next steps to take +* `awaiting more info`: If more info has been requested from the author, apply this label. +* `bug`: Issues that present a reasonable conviction there is a reproducible bug. +* `enhancement`: Issues that are found to be a reasonable candidate feature additions. + +If the issue is a question or discussion, it should be moved to GitHub Discussions. + +### Moving Discussions and Questions to GitHub Discussions + +For issues labeled with `question` or `discuss`, it is recommended to move them to GitHub Discussions instead: + +* **Questions**: User questions that do not appear to be bugs or enhancements should be moved to GitHub Discussions. +* **Discussions**: Topics for discussion should be moved to GitHub Discussions. If the discussion leads to a new feature or bug identification, it can be moved back to Issues. + +In all cases, issues may be closed by maintainers if they don't receive a timely response when +further information is sought, or when additional questions are asked. + +## Approaches and Best Practices for getting into triage contributions + +Review the organization's [StatusBoard](https://expressjs.github.io/statusboard/), +pay special attention to these columns: stars, watchers, open issues, and contributors. +This gives you a general idea about the criticality and health of the repository. +Pick a few projects based on that criteria, your interests, and skills (existing or aspiring). + +Review the project's contribution guideline if present. In a nutshell, +commit to the community's standards and values. Review the +documentation, for most of the projects it is just the README.md, and +make sure you understand the key APIs, semantics, configurations, and use cases. + +It might be helpful to write your own test apps to re-affirm your +understanding of the key functions. This may identify some gaps in +documentation, record those as they might be good PR's to open. +Skim through the issue backlog; identify low hanging issues and mostly new ones. +From those, attempt to recreate issues based on the OP description and +ask questions if required. No question is a bad question! + +## Removal of Triage Role + +There are a few cases where members can be removed as triagers: + +* Breaking the CoC or project contributor guidelines +* Abuse or misuse of the role as deemed by the TC +* Lack of participation for more than 6 months + +If any of these happen we will discuss as a part of the triage portion of the regular TC meetings. +If you have questions feel free to reach out to any of the TC members. + +## Other Helpful Hints + +* Everyone is welcome to attend the [Express Technical Committee Meetings](https://github.com/expressjs/discussions#expressjs-tc-meetings), and as a triager, it might help to get a better idea of what's happening with the project. +* When exploring the module's functionality there are a few helpful steps: + * Turn on `DEBUG=*` (see ) to get detailed log information + * It is also a good idea to do live debugging to follow the control flow, try using `node --inspect` + * It is a good idea to make at least one pass of reading through the entire source +* When reviewing the list of open issues there are some common types and suggested actions: + * New/unattended issues or simple questions: A good place to start + * Hard bugs & ongoing discussions: always feel free to chime in and help + * Issues that imply gaps in the documentation: open PRs with changes or help the user to do so +* For recurring issues, it is helpful to create functional examples to demonstrate (publish as gists or a repo) +* Review and identify the maintainers. If necessary, at-mention one or more of them if you are unsure what to do +* Make sure all your interactions are professional, welcoming, and respectful to the parties involved. +* When an issue refers to security concerns, responsibility is delegated to the repository captain or the security group in any public communication. + * If an issue has been open for a long time, the person in charge should be contacted internally through the private Slack chat. diff --git a/docs/rfc/0000-template.md b/docs/rfc/0000-template.md new file mode 100644 index 0000000..7daabe5 --- /dev/null +++ b/docs/rfc/0000-template.md @@ -0,0 +1,35 @@ +# {{TITLE: a human-readable title for this RFC!}} + +## Summary + +{{A concise, one-paragraph description of the change.}} + +## Motivation + +{{Why are we doing this? What pain points does this resolve? What use cases does it support? What is the expected outcome? Use real, concrete examples to make your case!}} + +## Detailed Explanation + +{{Describe the expected changes in detail, }} + +## Rationale and Alternatives + +{{Discuss 2-3 different alternative solutions that were considered. This is required, even if it seems like a stretch. Then explain why this is the best choice out of available ones.}} + +## Implementation + +{{Give a high-level overview of implementation requirements and concerns. Be specific about areas of code that need to change, and what their potential effects are. Discuss which repositories and sub-components will be affected, and what its overall code effect might be.}} + +{{THIS SECTION IS REQUIRED FOR RATIFICATION -- you can skip it if you don't know the technical details when first submitting the proposal, but it must be there before it's accepted}} + +## Prior Art + +{{This section is optional if there are no actual prior examples in other tools}} + +{{Discuss existing examples of this change in other tools, and how they've addressed various concerns discussed above, and what the effect of those decisions has been}} + +## Unresolved Questions and Bikeshedding + +{{Write about any arbitrary decisions that need to be made (syntax, colors, formatting, minor UX decisions), and any questions for the proposal that have not been answered.}} + +{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} diff --git a/package.json b/package.json new file mode 100644 index 0000000..636e5ad --- /dev/null +++ b/package.json @@ -0,0 +1,12 @@ +{ + "name": "discussions", + "private": true, + "scripts": { + "lint": "markdownlint-cli2", + "lint:fix": "markdownlint-cli2 --fix", + "test": "npm run lint" + }, + "devDependencies": { + "markdownlint-cli2": "^0.18.1" + } +}