From 8d93a1678c3a6ee73367ae497a71e35f506006ed Mon Sep 17 00:00:00 2001 From: crandmck Date: Wed, 11 May 2016 16:37:08 -0700 Subject: [PATCH 1/2] Add new page for governance info --- CONTRIBUTING.md | 39 +++---- README.md | 34 +----- _includes/header/header-en.html | 4 +- en/resources/contributing.md | 189 ++++++++++++++++++++++++++++++++ 4 files changed, 212 insertions(+), 54 deletions(-) create mode 100644 en/resources/contributing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ffe49d6b4..22de5c2ba7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,11 +4,26 @@ This repository is only for issues related to the website [http://expressjs.com] Feel free to make changes to the template files or the document files. The supporting docs are located in their respective directories, and the API docs are located under the `_includes` directory. -## Help translate the docs to other languages +## Contributing translations -We are looking for volunteers to help translate the Express docs to other languages. +**IMPORTANT:** We have professional translations of the Express documentation into: +- German +- French +- Italian +- Spanish +- Brazilian Portuguese +- Japanese +- Simplified Chinese +- Traditional Chinese +- Russian +- Korean -Interested? Please follow these steps: +Therefore we can no longer accept community translations for these languages, except for corrections +to the existing translations. + +We welcome contributions of translations into other languages, following the procedure below. + +Follow these steps: 0. Clone the [Express repository](https://github.com/strongloop/expressjs.com) 1. Create a directory for the language of your choice using its [ISO 639-1 code](http://www.loc.gov/standards/iso639-2/php/code_list.php) as its name. @@ -20,21 +35,3 @@ Interested? Please follow these steps: 7. Create the announcement file for the language in the `_includes/` directory. 8. Create a copy of the `_includes/api/en` and rename it according to the language code. 9. Make sure to append `/{{ page.lang }}` to all the links within the site. - -## Local Setup - -GitHub Pages websites being served through [Jekyll](http://jekyllrb.com/), you will need to replicate the setup on your local machine to preview the website locally. - -[Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) and [Jekyll](http://jekyllrb.com/docs/installation/) on your system, if you don't have them already. - -Once installed, `cd` to the repository directory and run Jekyll using the following command: - -``` -$ jekyll s -``` - -Then, load [http://localhost:4000/](http://localhost:4000/) on your browser. - -Jekyll uses a variant of Markdown known as [Kramdown](http://kramdown.gettalong.org/quickref.html), read up the docs if you need to go beyond basic Markdown in the doc files. - -To understand the template system used by Jekyll, read up the [Liquid template engine docs](http://liquidmarkup.org/). diff --git a/README.md b/README.md index 1fa1d0efdb..74b7a84be2 100644 --- a/README.md +++ b/README.md @@ -50,38 +50,8 @@ The default GitHub Pages syntax highlighting has been disabled in `_config.yml t Feel free to make changes to the template files or the document files. The supporting docs are located in their respective directories, and the API docs are located under the `_includes` directory. +Please see the [Contributors' Guide](CONTRIBUTING.md) for more information on contributing to the documentation, including information on contributing translations. + ## Why use Jekyll instead of an Express-based solution? Jekyll comes built-in with GitHub Pages. Since we are already using GitHub Pages to host the website, it makes sense to leverage the capabilities it provides. It's all about using the right tool, for the right job, under the right circumstances. - -## How do I help translate the docs to another language? - -**IMPORTANT:** We have professional translations of the Express documentation into: -- German -- French -- Italian -- Spanish -- Brazilian Portuguese -- Japanese -- Simplified Chinese -- Traditional Chinese -- Russian -- Korean - -Therefore we can no longer accept community translations for these languages, except for corrections -to the existing translations. - -We welcome contributions of translations into other languages, following the procedure below. - -Follow these steps: - -0. Clone the [Express repository](https://github.com/strongloop/expressjs.com) -1. Create a directory for the language of your choice using its [ISO 639-1 code](http://www.loc.gov/standards/iso639-2/php/code_list.php) as its name. -2. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory. -3. Remove the link to 2.x docs from the "API Reference" menu. -4. Update the `lang` variable in the copied markdown files. -5. Update the `title` variable in the copied markdown files. -6. Create the header, footer, notice, and announcement file for the language in the `_includes/` directory, in the respective directories, and make necessary edits to the contents. -7. Create the announcement file for the language in the `_includes/` directory. -8. Create a copy of the `_includes/api/en` and rename it according to the language code. -9. Make sure to append `/{{ page.lang }}` to all the links within the site. diff --git a/_includes/header/header-en.html b/_includes/header/header-en.html index b6f03e71c7..11319dafdc 100755 --- a/_includes/header/header-en.html +++ b/_includes/header/header-en.html @@ -101,7 +101,6 @@
  • Performance best practices
    • - @@ -128,6 +127,9 @@
  • Companies using Express
    • +
  • + Contributing to Express +
    • diff --git a/en/resources/contributing.md b/en/resources/contributing.md new file mode 100644 index 0000000000..f03e1c1d7e --- /dev/null +++ b/en/resources/contributing.md @@ -0,0 +1,189 @@ +--- +layout: page +title: Contributing to Express +menu: resources +lang: en +redirect_from: "/resources/community.html" +--- + +# Contributing to Express + +Express and the other projects in the [expressjs organization on GitHub](https://github.com/expressjs) are projects of the [Node.js Foundation](https://nodejs.org/foundation/). +These projects are governed under the general policies and guidelines of the Node.js Foundation along with the additional guidelines below. + +* [Community contributing guide](#community-contributing-guide) +* [Collaborator's guide](#collaborators-guide) +* [Security policies and procedures](#security-policies-and-procedures) + +## Community contributing guide + +> NOTE: This is copied from the [Contributing Guide in the repo](https://github.com/expressjs/express/blob/master/Contributing.md). + +The goal of this guide 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 which makes it clear how +contributors can be involved in decision making. + +This document is based on much prior art in the Node.js community, io.js, +and the Node.js project. + +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 **TC (Technical Committee)** is a group of committers representing the required technical +expertise to resolve rare disputes. + +### Logging issues + +Log an issue for any question or problem you might have. When in doubt, log an issue, +any additional policies about what to include will be provided in the responses. The only +exception is security dislosures 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, respectful, and 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 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 committer + +All contributors who land a non-trivial contribution should be on-boarded 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 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. + +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. + +## Express collaborator guide + +> NOTE: This is copied from the [Collaborator guide in the repo](https://github.com/expressjs/express/blob/master/Collaborator-Guide.md). + +### Website Issues + +Open issues for the expressjs.com website in https://github.com/strongloop/expressjs.com. + +### PRs and code contributions + +* Tests must pass. +* Follow existing coding style. +* If you fix a bug, add a test. + +### Branches + +* Use the `master` branch for bug fixes or minor work that is intended for the current release stream +* Use the correspondingly named branch, e.g. `5.0`, for anything intended for a future release of Express + +### Steps for contributing + +* [Create an issue](https://github.com/strongloop/express/issues/new) for the bug you want to fix or the feature that you want to add. +* Create your own [fork](https://github.com/strongloop/express) on github, then checkout your fork. +* Write your code in your local copy. It's good practice to create a branch for each new issue you work on, although not compulsory. +* To run the test suite, first install the dependencies by running `npm install`, then run `npm test`. +* If the tests pass, you can commit your changes to your fork and then create a pull request from there. Make sure to reference your issue from the pull request comments by including the issue number e.g. #123. + +### Issues which are questions + +We will typically close any vague issues or questions that are specific to some app you are writing. Please double check the docs and other references before being trigger happy with posting a question issue. + +Things that will help get your question issue looked at: + +* Full and runnable JS code. +* Clear description of the problem or unexpected behavior. +* Clear description of the expected result. +* Steps you have taken to debug it yourself. + +If you post a question and do not outline the above items or make it easy for us to understand and reproduce your issue, it will be closed. + +## Security Policies and Procedures + +This document outlines security procedures and general policies for the Express +project. + + * [Reporting a Bug](#reporting-a-bug) + * [Disclosure Policy](#disclosure-policy) + * [Comments on this Policy](#comments-on-this-policy) + +### Reporting a Bug + +The Express team and community take all security bugs in Express seriously. +Thank you for improving the security of Express. We appreciate your efforts and +responsible disclosure and will make every effort to acknowledge your +contributions. + +Report security bugs by emailing the lead maintainer in the Readme.md file. + +The lead maintainer will acknowledge your email within 48 hours, and will send a +more detailed response within 48 hours indicating the next steps in handling +your report. After the initial reply to your report, the security team will +endeavor to keep you informed of the progress towards a fix and full +announcement, and may ask for additional information or guidance. + +Report security bugs in third-party modules to the person or team maintaining +the module. You can also report a vulnerability through the +[Node Security Project](https://nodesecurity.io/report). + +### Disclosure Policy + +When the security team receives a security bug report, they will assign it to a +primary handler. This person will coordinate the fix and release process, +involving the following steps: + + * Confirm the problem and determine the affected versions. + * Audit code to find any potential similar problems. + * Prepare fixes for all releases still under maintenance. These fixes will be + released as fast as possible to npm. + +### Comments on this Policy + +If you have suggestions on how this process could be improved please submit a +pull request. From c78316faf2f1fe8579b8e37fe8db3e74e0a3fc4c Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 12 May 2016 13:55:21 -0700 Subject: [PATCH 2/2] Change `strongloop` to `expressjs` in repo URLs --- en/resources/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/resources/contributing.md b/en/resources/contributing.md index f03e1c1d7e..6029754edc 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -110,7 +110,7 @@ a majority of the other members are expected to resign. ### Website Issues -Open issues for the expressjs.com website in https://github.com/strongloop/expressjs.com. +Open issues for the expressjs.com website in https://github.com/expressjs/expressjs.com. ### PRs and code contributions @@ -125,8 +125,8 @@ Open issues for the expressjs.com website in https://github.com/strongloop/expre ### Steps for contributing -* [Create an issue](https://github.com/strongloop/express/issues/new) for the bug you want to fix or the feature that you want to add. -* Create your own [fork](https://github.com/strongloop/express) on github, then checkout your fork. +* [Create an issue](https://github.com/expressjs/express/issues/new) for the bug you want to fix or the feature that you want to add. +* Create your own [fork](https://github.com/expressjs/express) on github, then checkout your fork. * Write your code in your local copy. It's good practice to create a branch for each new issue you work on, although not compulsory. * To run the test suite, first install the dependencies by running `npm install`, then run `npm test`. * If the tests pass, you can commit your changes to your fork and then create a pull request from there. Make sure to reference your issue from the pull request comments by including the issue number e.g. #123.