diff --git a/docs/CHARTER.md b/docs/CHARTER.md new file mode 100644 index 0000000..1f86bbd --- /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 \ No newline at end of file diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md new file mode 100644 index 0000000..5dd4be7 --- /dev/null +++ b/docs/GOVERNANCE.md @@ -0,0 +1,184 @@ +# 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](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) + +## 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. +``` \ No newline at end of file diff --git a/docs/contributing/captains_and_committers.md b/docs/contributing/captains_and_committers.md new file mode 100644 index 0000000..eebb041 --- /dev/null +++ b/docs/contributing/captains_and_committers.md @@ -0,0 +1,83 @@ +### 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: @wesleytodd, @jonchurch, @ulisesGascon + - Committers: @Phillip9587 +- [`expressjs/codemod`](https://github.com/expressjs/codemod): @bjohansebas (npm: `@bsebas`), @kjugi (npm: `@filip.kudla`) +- [`expressjs/compression`](https://github.com/expressjs/compression): + - captains: @UlisesGascon + - committers: @bjohansebas +- [`expressjs/connect-multiparty`](https://github.com/expressjs/connect-multiparty): @ulisesGascon +- [`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-paginate`](https://github.com/expressjs/express-paginate): @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, @chrisdel101 +- [`expressjs/flash`](https://github.com/expressjs/flash): @ulisesGascon +- [`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): @wesleytodd, @ulisesGascon +- [`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/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 [ref](https://github.com/expressjs/discussions/issues/227): @UlisesGascon \ No newline at end of file diff --git a/docs/contributing/readme-guide.md b/docs/contributing/readme-guide.md new file mode 100644 index 0000000..03edbd2 --- /dev/null +++ b/docs/contributing/readme-guide.md @@ -0,0 +1,123 @@ +# 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 https://expressjs.com/en/resources/middleware.html. +- 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: + +``` +### Function_name(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. \ No newline at end of file diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md new file mode 100644 index 0000000..32efc20 --- /dev/null +++ b/docs/contributing/release-process.md @@ -0,0 +1,202 @@ +# 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 Express, +as npm packages hosted on https://npmjs.com/package/express. + +## Who can make releases? + +Release authorization is given by the Express TC. Once authorized, an individual +must have the following access permissions: + +### 1. Github release access + +The individual making the release will need to be a member of the +expressjs/express team with Write permission level so they are able to tag the +release commit and push changes to the expressjs/express repository +(see Steps 4 and 5). + +### 2. npmjs.com release access + +The individual making the release will need to be made an owner on the +`express` 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 - https://semver.org) +- 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 +(https://github.com/expressjs/express). + +```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 https://expressjs.com/ 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. \ No newline at end of file diff --git a/docs/contributing/triager-guide.md b/docs/contributing/triager-guide.md new file mode 100644 index 0000000..65aff26 --- /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 https://www.npmjs.com/package/debug) 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. \ No newline at end of file