From 1d1346ddeb4f1b3c35cdc2967346d5f8a7e76ea9 Mon Sep 17 00:00:00 2001 From: Chris Del Date: Mon, 11 Nov 2024 22:07:45 -0600 Subject: [PATCH 01/13] add contrbuting changes --- CONTRIBUTING.md | 129 ++++++++++++++++++++++++----------- en/resources/contributing.md | 8 +++ 2 files changed, 97 insertions(+), 40 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 861b75f790..a07c9e9aa4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,55 +1,104 @@ -## Contributing to expressjs.com +# Contributing to Expressjs.com -This repository is only for issues related to the website [http://expressjs.com](http://expressjs.com). For issues related to Express, the framework, go to [https://github.com/expressjs/express](https://github.com/expressjs/express). +### The Offical Documentation of the Express Framework -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. +**NOTE**: This is not the repo for Express JS. To contribute to the _[Express JS framework](https://github.com/expressjs/express)_ itself, [check this out](#were-the-express-js-frameworks-documetation-team---not-the-express-js-framework). -Content on this site is licensed under a Creative Commons Attribution-ShareAlike 3.0 United States License. See https://creativecommons.org/licenses/by-sa/3.0/us/ for a layman's summary; -See [LICENSE.md](LICENSE.md) for the full license. +If you want to contribute to [https://github.com/expressjs/expressjs.com](https://github.com/expressjs/expressjs.com), you're in the right place. -## Contributing translations -We highly encourage community translations! We no longer have professional translations, and we believe in the power of our community to provide accurate and helpful translations. +Whether you're a first time first time contributor or you're just looking for a refresher, visit our [Getting Started](#contributors-guide-to-getting-started) guide below to get up and runnning. -The documentation is translated into these languages: -- English (`en`) -- Spanish (`es`) -- French (`fr`) -- Italian (`it`) -- Indonesian (`id`) -- Japanese (`ja`) -- Korean (`ko`) -- Brazilian Portuguese (`pt-br`) -- Russian (`ru`) -- Slovak (`sk`) -- Thai (`th`) -- Turkish (`tr`) -- Ukrainian (`uk`) -- Uzbek (`uz`) -- Simplified Chinese (`zh-cn`) -- Traditional Chinese (`zh-tw`) +#### Want to help but need some ideas? These are some of our most typical issue types: -To find translations that need to be done, you can [filter for merged PRs](https://github.com/expressjs/expressjs.com/pulls?q=is%3Apr+is%3Aclosed+label%3Arequires-translation-es) that include the tag for your language, such as `requires-translation-es`. +1. **Website Related**: +If you see anything on the site that could use a tune-up, think about how to fix it. -When you contribute a translation, please reference the original PR. This helps the person merging your translation to remove the `requires-translation-es` tag from the original PR. + - display or screen sizing problems + - mobile responsiveness issues + - missing or broken accessibility features + - website outages + - broken links + - page structure or user interface enhancements -### Adding new translations +2. **Content Related**: spelling errors, incorrect/outdated Express documentation, adding missing content. + - _We love any reports of typos. If you see one, fixing it is a great way to help_. -To contribute a translation into another language, following the procedure below. -Follow these steps: +3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. + - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. -0. Clone the [`expressjs.com` repository](https://github.com/expressjs/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. -9. Make sure to append `/{{ page.lang }}` to all the links within the site. -10. Update the `CONTRIBUTING.md` and the `.github/workflows/translation.yml` files with the new language +#### Want to work on a backlog issue? +We often have bugs or enhancements that need work. You can find these on our repo [https://github.com/expressjs/expressjs.com/issues](https://github.com/expressjs/expressjs.com/issues). Check out the tags to find something that's a good match for you. -Thank you for your interest in contributing to expressjs.com. Your efforts help make our documentation accessible to everyone! \ No newline at end of file +#### Have an idea? Found a bug? + +If you've found a bug or a typo, or if you have an idea for an enhancement, please submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). You can do this by going to our [repo](https://github.com/expressjs/expressjs.com) and opening a "New Issue" under the **Issues** tab. If you submit it, we will respond. + +## Contributor's Guide to Getting Started + +If you want to learn about working on Expressjs.com, this is the right place. Follow the steps below to get started. + +#### TL;DR +1. Open an issue and get approval. +2. Make your pull request, and celebrate being a contributor. + + +#### Step1: Opening a New Issue +So, you've found a problem that you want to fix, or have a site enhancement you want to make. +1. The first step is to open an [issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md), not a PR. + - Give the issue a good title and be sure to fill in the description section, writing as much detail on your proposal as possible . + - Don't leave anything blank! If you leave the description section blank we will not read it and it will almost certainly be rejected. Fill in the details! + + +2. Next, the Express documentation team will respond, either approving or denying your proposal. We read all submissions and try our best to always respond quickly with feedback. + - After you've received approval, *only then* should you start work or make any pull requests. + - If you really want to see you work merged into a super popular open source project, *and you do*, please always follow our process and open an issue first. + - __Don't skip straight to a pull request__. It will be likely be rejected and closed. We DO NOT want anyone's time or hard work to go to waste. So please, follow the steps. + +#### Step2: Get the Application Code Base + +After you've been approved, now you can clone the repo and get the code. +- `git clone https://github.com/expressjs/expressjs.com.git` + +This is a list of the main sections of the application, where most changes are likely to be made. This may help you identify where files you need to change live. + +**Markdown Page Files**: +- These files render to html and make up the individual pages of the site. Most of the site's documentation text content is written in `md` files. +- Change these to make changes to individual pages' content/text or markup. +- Each translation has it's own complete set of pages, located under their respective language directories. Ex. English middleware page is located at `en > resources > middleware.md.` + +**Template Includes and Layout Files** +- These file are page components that make up the user interface and periphery structure. Ex. Header, Footer, etc. +- There are also markdown files here that are *included* within other larger files. Ex `api > en` holds the API Reference text content. +- Change these to make changes to page layouts or site-wide structures, or to change the API Reference documentation. +- Located mainly under `_includes` and `_layouts`. API markdown and text content are located under `_includes/api`. + +**Blog Markdown Files** +- These files make up the individual blog posts. If you want to contribute a blog post please +follow the specific instructions for [How to write a blog post.](https://expressjs.com/en/blog/write-post.html) +- Located under the `_posts` directory. + +**CSS or Javascript** +- All css and js files are kept in `css` and `js` folders on the project root. + +#### Step3: Running the Application + + +Now you'll need a way to see your changes, which means you'll need a running version of the application. You have two options. +1. __Run Locally__: This gets the local version of the application up and running on your machine. Follow our [Local Setup Guide](https://github.com/expressjs/expressjs.com?tab=readme-ov-file#local-setup) to use this option. + - This is the recommended option for moderate to complex work. +2. __Run using Deploy Preview__: Use this option if you don't want to bother with a local installation. Part of our continuous integration pipeline includes [Netlify Deploy Preview](https://docs.netlify.com/site-deploys/deploy-previews/). + - To use this you'll need to get your changes online - after you've made your first commit on your feature branch, make a *draft* pull request. + - After the build steps are complete, you'll have access to a __Deploy Preview__ tab that will run your changes on the web, rebuilding after each commit is pushed. + - After you are completely done your work and it's ready for review, remove the draft status on your pull request and submit your work. We will review it and respond. + +{% include contributing/translations.md %} + +## We're the Express JS Framework's Documetation Team - Not the Express JS Framework + +If you are looking for the repository for the **Express JS Framework**, you've hopefully noticed by now that you've come to the wrong place. This page is only for issues related to the this website: [http://expressjs.com](http://expressjs.com). + +For more information on contributing to Express itself, check our out our [Contributing to Express](/{{ page.lang }}/resources/contributing.html) page. For anything else, visit the repository [https://github.com/expressjs/express](https://github.com/expressjs/express). \ No newline at end of file diff --git a/en/resources/contributing.md b/en/resources/contributing.md index 6013011ef9..30ad4e5f9e 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -5,10 +5,14 @@ description: Find out how to contribute to Express.js, including guidelines for menu: resources lang: en redirect_from: "/resources/community.html" +title2: Contributing to Expressjs.com +sub-title: The official documentation for the Express framework. --- # Contributing to Express +### Looking to contribute to expressjs.com? Click [here](#contributing-to-expressjscom). + Express and the other projects in the [expressjs organization on GitHub](https://github.com/expressjs) are projects of the [OpenJs Foundation](https://openjsf.org/). These projects are governed under the general policies and guidelines of the Node.js Foundation along with the additional guidelines below. @@ -374,3 +378,7 @@ We are currently working on a new version of the security model, the most update If you have suggestions on how this process could be improved please submit a pull request. +---- +# Contributing to Expressjs.com + + From 88c992f1047f082fbf55e9172e6051944b1662c1 Mon Sep 17 00:00:00 2001 From: Chris Del Date: Tue, 12 Nov 2024 20:37:50 -0600 Subject: [PATCH 02/13] Reset history to match upstream - apply all branch changes --- .github/scripts/get-contributing.sh | 43 +++++++++++++++++++++++++---- README.md | 4 +-- en/resources/contributing.md | 3 +- 3 files changed, 39 insertions(+), 11 deletions(-) diff --git a/.github/scripts/get-contributing.sh b/.github/scripts/get-contributing.sh index 0722a7c500..4364d15c30 100755 --- a/.github/scripts/get-contributing.sh +++ b/.github/scripts/get-contributing.sh @@ -1,35 +1,66 @@ #!/bin/bash -DEST="../../en/resources/contributing.md" +DEST="./en/resources/contributing.md" # This script replaces the contents of a section with the contents from # the annotated source address. +# tracks the header level level='' +# tracks repo & file for curl call src='' +# tracks file for local file copy +local='' while IFS= read -r line; do - if [[ -n "$src" ]] && [[ "$line" != '#'* || "$line" == "$level"'#'* ]]; then - continue + # this section removes prev lines after file loads - src/load set to non-empty + if [[ -n "$src" || -n "$local" ]]; then + # if line eq level - level is num of ##s + if [[ "$line" == "$level"'#'* || + # line not a header) + "$line" != '#'* ]]; then + continue + fi fi src='' + local='' + # if line is header - assign level num if [[ "$line" == '#'* ]]; then + # this is header before SRC/LOCAL anchors title=${line##*\#} level="${line:0:$((${#line} - ${#title}))}" + # src on page elif [[ "$line" == ' + From 518a22f1e4b9de87efec5c3b658a531c1a2f658b Mon Sep 17 00:00:00 2001 From: Chris Del Date: Tue, 12 Nov 2024 20:57:00 -0600 Subject: [PATCH 03/13] remove unused script file changes to soften workflow language --- CONTRIBUTING.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a07c9e9aa4..b7a0b8d639 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,7 @@ If you see anything on the site that could use a tune-up, think about how to fix 3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. + > [!IMPORTANT]: All translation submissions are currently paused. See this [notice](#important-notice-we-have-paused-all-translation-contributions) for more information. - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. #### Want to work on a backlog issue? @@ -48,15 +49,15 @@ If you want to learn about working on Expressjs.com, this is the right place. Fo #### Step1: Opening a New Issue So, you've found a problem that you want to fix, or have a site enhancement you want to make. -1. The first step is to open an [issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md), not a PR. - - Give the issue a good title and be sure to fill in the description section, writing as much detail on your proposal as possible . - - Don't leave anything blank! If you leave the description section blank we will not read it and it will almost certainly be rejected. Fill in the details! +1. The first step is to open an [issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). + - Give the issue a good title and be sure to fill in the description section, writing as much detail on your proposal as possible. + - Don't leave anything blank! The more details you provide the more feedback we can give. -2. Next, the Express documentation team will respond, either approving or denying your proposal. We read all submissions and try our best to always respond quickly with feedback. +2. Next, the Express documentation team will respond with feedback on your submission. We read all submissions and try our best to always respond quickly with feedback. - After you've received approval, *only then* should you start work or make any pull requests. - If you really want to see you work merged into a super popular open source project, *and you do*, please always follow our process and open an issue first. - - __Don't skip straight to a pull request__. It will be likely be rejected and closed. We DO NOT want anyone's time or hard work to go to waste. So please, follow the steps. + - __Please don't skip straight to a pull request unless you are totally sure your work is unique__. This is just because we never want anyone's time or hard work to go to waste on dulicated work. #### Step2: Get the Application Code Base From 9f2d071429d0733a65753a02cf2c1e371e7a9f0e Mon Sep 17 00:00:00 2001 From: Chris Del Date: Tue, 12 Nov 2024 21:07:07 -0600 Subject: [PATCH 04/13] Update CONTRIBUTING.md Add gh important tags to top of page --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b7a0b8d639..3ec625376e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,8 +27,10 @@ If you see anything on the site that could use a tune-up, think about how to fix 3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. - > [!IMPORTANT]: All translation submissions are currently paused. See this [notice](#important-notice-we-have-paused-all-translation-contributions) for more information. - - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. +> [!IMPORTANT] +> All translation submissions are currently paused. See this [notice](#important-notice-we-have-paused-all-translation-contributions) for more information. + + - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. #### Want to work on a backlog issue? From ad7cd69c20277d52e06a88d440fae39817435c4c Mon Sep 17 00:00:00 2001 From: chris del Date: Thu, 14 Nov 2024 16:20:43 -0600 Subject: [PATCH 05/13] Add corrections for CI paths --- .github/scripts/get-contributing.sh | 4 ++-- en/resources/contributing.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/scripts/get-contributing.sh b/.github/scripts/get-contributing.sh index 4364d15c30..d61494cfd1 100755 --- a/.github/scripts/get-contributing.sh +++ b/.github/scripts/get-contributing.sh @@ -1,6 +1,6 @@ #!/bin/bash -DEST="./en/resources/contributing.md" +DEST="../../en/resources/contributing.md" # This script replaces the contents of a section with the contents from # the annotated source address. @@ -43,7 +43,7 @@ while IFS= read -r line; do echo "$line" if [[ -n "$local" ]]; then - cat "./$local" | \ + cat "$local" | \ # remove the top # headers from cp file sed -En '/^##|^[^#]/,$p' | \ # remove any starting w NOTE: lines diff --git a/en/resources/contributing.md b/en/resources/contributing.md index 4abd4e1545..8a6e4c7491 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -380,4 +380,4 @@ pull request. # Contributing to Expressjs.com - + From 3e3116a3b78141cd051f05adb0b7e910b68d22b6 Mon Sep 17 00:00:00 2001 From: chris del Date: Thu, 14 Nov 2024 16:41:33 -0600 Subject: [PATCH 06/13] small text changes to contrib --- CONTRIBUTING.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ec625376e..77a761a47c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,7 +98,54 @@ Now you'll need a way to see your changes, which means you'll need a running ver - After the build steps are complete, you'll have access to a __Deploy Preview__ tab that will run your changes on the web, rebuilding after each commit is pushed. - After you are completely done your work and it's ready for review, remove the draft status on your pull request and submit your work. We will review it and respond. -{% include contributing/translations.md %} +## Contributing translations + +#### Important Notice: We have paused all translation contributions. +> [!IMPORTANT] +> We are currently working toward a more streamlined translations workflow. As long as this notice is posted, we will _not_ be accepting any translation submissions. + +We highly encourage community translations! We no longer have professional translations, and we believe in the power of our community to provide accurate and helpful translations. + +The documentation is translated into these languages: +- English (`en`) +- Spanish (`es`) +- French (`fr`) +- Italian (`it`) +- Indonesian (`id`) +- Japanese (`ja`) +- Korean (`ko`) +- Brazilian Portuguese (`pt-br`) +- Russian (`ru`) +- Slovak (`sk`) +- Thai (`th`) +- Turkish (`tr`) +- Ukrainian (`uk`) +- Uzbek (`uz`) +- Simplified Chinese (`zh-cn`) +- Traditional Chinese (`zh-tw`) + +### Adding New Full Site Translations + +If you find a translation is missing from the list you can create a new one. + +To translate expressjs.com into a new language, follow these steps: + +1. Clone the [`expressjs.com`](https://github.com/expressjs/expressjs.com) repository. +2. 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. +3. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory. +4. Remove the link to 2.x docs from the "API Reference" menu. +5. Update the `lang` variable in the copied markdown files. +6. Update the `title` variable in the copied markdown files. +7. 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. +8. Create the announcement file for the language in the `_includes/` directory. +9. Make sure to append `/{{ page.lang }}` to all the links within the site. +10. Update the `CONTRIBUTING.md` and the `.github/workflows/translation.yml` files with the new language. + +### Adding Page and Section Translations + +Many site translations are still missing pages. To find which ones we need help with, you can [filter for merged PRs](https://github.com/expressjs/expressjs.com/pulls?q=is%3Apr+is%3Aclosed+label%3Arequires-translation-es) that include the tag for your language, such as `requires-translation-es` for requires Spanish translation. + +If you contribute a page or section translation, please reference the original PR. This helps the person merging your translation to remove the tag from the original PR. ## We're the Express JS Framework's Documetation Team - Not the Express JS Framework From 823e960397b09a3171c46b3ce4cc5052a7c4d0b7 Mon Sep 17 00:00:00 2001 From: chris del Date: Thu, 14 Nov 2024 16:54:18 -0600 Subject: [PATCH 07/13] Fix typos/spelling --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77a761a47c..1842ed83de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,13 @@ # Contributing to Expressjs.com -### The Offical Documentation of the Express Framework +### The Official Documentation of the Express Framework -**NOTE**: This is not the repo for Express JS. To contribute to the _[Express JS framework](https://github.com/expressjs/express)_ itself, [check this out](#were-the-express-js-frameworks-documetation-team---not-the-express-js-framework). +**NOTE**: This is not the repo for Express JS. To contribute to the _[Express JS framework](https://github.com/expressjs/express)_ itself, [check this out](#were-the-express-js-frameworks-documenntation-team---not-the-express-js-framework). If you want to contribute to [https://github.com/expressjs/expressjs.com](https://github.com/expressjs/expressjs.com), you're in the right place. -Whether you're a first time first time contributor or you're just looking for a refresher, visit our [Getting Started](#contributors-guide-to-getting-started) guide below to get up and runnning. +Whether you're a first time first time contributor or you're just looking for a refresher, visit our [Getting Started](#contributors-guide-to-getting-started) guide below to get up and running. #### Want to help but need some ideas? These are some of our most typical issue types: @@ -59,7 +59,7 @@ So, you've found a problem that you want to fix, or have a site enhancement you 2. Next, the Express documentation team will respond with feedback on your submission. We read all submissions and try our best to always respond quickly with feedback. - After you've received approval, *only then* should you start work or make any pull requests. - If you really want to see you work merged into a super popular open source project, *and you do*, please always follow our process and open an issue first. - - __Please don't skip straight to a pull request unless you are totally sure your work is unique__. This is just because we never want anyone's time or hard work to go to waste on dulicated work. + - __Please don't skip straight to a pull request unless you are totally sure your work is unique__. This is just because we never want anyone's time or hard work to go to waste on duplicated work. #### Step2: Get the Application Code Base @@ -147,7 +147,7 @@ Many site translations are still missing pages. To find which ones we need help If you contribute a page or section translation, please reference the original PR. This helps the person merging your translation to remove the tag from the original PR. -## We're the Express JS Framework's Documetation Team - Not the Express JS Framework +## We're the Express JS Framework's Documentation Team - Not the Express JS Framework If you are looking for the repository for the **Express JS Framework**, you've hopefully noticed by now that you've come to the wrong place. This page is only for issues related to the this website: [http://expressjs.com](http://expressjs.com). From 2addced41d2ff75eac9aeebe75c90dd6326a5953 Mon Sep 17 00:00:00 2001 From: Chris Del Date: Thu, 14 Nov 2024 20:58:32 -0600 Subject: [PATCH 08/13] Add uz.css file to fix error --- css/uz.css | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 css/uz.css diff --git a/css/uz.css b/css/uz.css new file mode 100644 index 0000000000..1b920cecdf --- /dev/null +++ b/css/uz.css @@ -0,0 +1,17 @@ +/* + Copyright (c) 2016 StrongLoop, IBM, and Express Contributors + License: MIT +*/ +/* For image callouts in writing-middleware.md */ + +#callout1 {top: 40px; } + +#callout2 {top: 60px;} + +#callout3 {top: 75px;} + +#callout4 {top: 145px;} + +#callout5 {top: 170px;} + +#callout6 {top: 195px;} From 2371fa1718e299ba3ec0380aeb4acae0e79a890c Mon Sep 17 00:00:00 2001 From: chris del Date: Mon, 18 Nov 2024 09:22:58 -0600 Subject: [PATCH 09/13] #1683 request changes work --- .github/scripts/get-contributing.sh | 11 ++++++----- CONTRIBUTING.md | 6 +++--- en/resources/contributing.md | 4 ++-- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/.github/scripts/get-contributing.sh b/.github/scripts/get-contributing.sh index d61494cfd1..6bae4e4100 100755 --- a/.github/scripts/get-contributing.sh +++ b/.github/scripts/get-contributing.sh @@ -1,6 +1,6 @@ #!/bin/bash -DEST="../../en/resources/contributing.md" +DEST="./en/resources/contributing.md" # This script replaces the contents of a section with the contents from # the annotated source address. @@ -44,12 +44,13 @@ while IFS= read -r line; do if [[ -n "$local" ]]; then cat "$local" | \ - # remove the top # headers from cp file + # remove the top 1# headers from cat'd file sed -En '/^##|^[^#]/,$p' | \ - # remove any starting w NOTE: lines + # remove any ln starting w 'NOTE: lines' sed -E '/^[NOTE:*]/d' | \ - # remove any lines with Not the Express JS Framework string - sed -E '/Not the Express JS Framework/I,$d' + # remove any lines with 'Not the Express JS Framework' + sed -E '/Not the Express JS Framework/I,$d' | \ + sed -E 's/> \[!IMPORTANT\]/> **IMORTANT:** /g' echo elif [[ -n "$src" ]]; then echo diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1842ed83de..ba3a8e7fee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,7 +131,7 @@ If you find a translation is missing from the list you can create a new one. To translate expressjs.com into a new language, follow these steps: 1. Clone the [`expressjs.com`](https://github.com/expressjs/expressjs.com) repository. -2. 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. Create a directory for the language of your choice using its [ISO 639-1 code](https://www.loc.gov/standards/iso639-2/php/code_list.php) as its name. 3. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory. 4. Remove the link to 2.x docs from the "API Reference" menu. 5. Update the `lang` variable in the copied markdown files. @@ -139,7 +139,7 @@ To translate expressjs.com into a new language, follow these steps: 7. 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. 8. Create the announcement file for the language in the `_includes/` directory. 9. Make sure to append `/{{ page.lang }}` to all the links within the site. -10. Update the `CONTRIBUTING.md` and the `.github/workflows/translation.yml` files with the new language. +10. Update the [CONTRIBUTING.md](https://github.com/expressjs/expressjs.com/blob/gh-pages/CONTRIBUTING.md#contributing-translations) and the `.github/workflows/translation.yml` files with the new language. ### Adding Page and Section Translations @@ -149,6 +149,6 @@ If you contribute a page or section translation, please reference the original P ## We're the Express JS Framework's Documentation Team - Not the Express JS Framework -If you are looking for the repository for the **Express JS Framework**, you've hopefully noticed by now that you've come to the wrong place. This page is only for issues related to the this website: [http://expressjs.com](http://expressjs.com). +If you are looking for the repository for the **Express JS Framework**, you've hopefully noticed by now that you've come to the wrong place. This page is only for issues related to the this website: [https://expressjs.com](https://expressjs.com). For more information on contributing to Express itself, check our out our [Contributing to Express](/{{ page.lang }}/resources/contributing.html) page. For anything else, visit the repository [https://github.com/expressjs/express](https://github.com/expressjs/express). \ No newline at end of file diff --git a/en/resources/contributing.md b/en/resources/contributing.md index 8a6e4c7491..04567b69bc 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -11,7 +11,7 @@ sub-title: The official documentation for the Express framework. # Contributing to Express -### Looking to contribute to expressjs.com? Click [here](#contributing-to-expressjscom). +### Looking to contribute to expressjs.com? Click [here](#expressjs-website-contributing). Express and the other projects in the [expressjs organization on GitHub](https://github.com/expressjs) are projects of the [OpenJs Foundation](https://openjsf.org/). These projects are governed under the general policies and guidelines of the Node.js Foundation along with the additional guidelines below. @@ -378,6 +378,6 @@ We are currently working on a new version of the security model, the most update If you have suggestions on how this process could be improved please submit a pull request. -# Contributing to Expressjs.com +# Contributing to Expressjs.com {#expressjs-website-contributing} From b17d5d174ab950c929bf6cf850543a5e427fe74d Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sun, 17 Nov 2024 12:53:46 -0500 Subject: [PATCH 10/13] run script --- en/resources/contributing.md | 139 +++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/en/resources/contributing.md b/en/resources/contributing.md index 04567b69bc..b1ae575940 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -381,3 +381,142 @@ pull request. # Contributing to Expressjs.com {#expressjs-website-contributing} +### The Official Documentation of the Express Framework + + +If you want to contribute to [https://github.com/expressjs/expressjs.com](https://github.com/expressjs/expressjs.com), you're in the right place. + + +Whether you're a first time first time contributor or you're just looking for a refresher, visit our [Getting Started](#contributors-guide-to-getting-started) guide below to get up and running. + +#### Want to help but need some ideas? These are some of our most typical issue types: + +1. **Website Related**: +If you see anything on the site that could use a tune-up, think about how to fix it. + + - display or screen sizing problems + - mobile responsiveness issues + - missing or broken accessibility features + - website outages + - broken links + - page structure or user interface enhancements + + +2. **Content Related**: spelling errors, incorrect/outdated Express documentation, adding missing content. + - _We love any reports of typos. If you see one, fixing it is a great way to help_. + + +3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. +> [!IMPORTANT] +> All translation submissions are currently paused. See this [notice](#important-notice-we-have-paused-all-translation-contributions) for more information. + + - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. + +#### Want to work on a backlog issue? + +We often have bugs or enhancements that need work. You can find these on our repo [https://github.com/expressjs/expressjs.com/issues](https://github.com/expressjs/expressjs.com/issues). Check out the tags to find something that's a good match for you. + +#### Have an idea? Found a bug? + +If you've found a bug or a typo, or if you have an idea for an enhancement, please submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). You can do this by going to our [repo](https://github.com/expressjs/expressjs.com) and opening a "New Issue" under the **Issues** tab. If you submit it, we will respond. + +## Contributor's Guide to Getting Started + +If you want to learn about working on Expressjs.com, this is the right place. Follow the steps below to get started. + +#### TL;DR +1. Open an issue and get approval. +2. Make your pull request, and celebrate being a contributor. + + +#### Step1: Opening a New Issue +So, you've found a problem that you want to fix, or have a site enhancement you want to make. +1. The first step is to open an [issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). + - Give the issue a good title and be sure to fill in the description section, writing as much detail on your proposal as possible. + - Don't leave anything blank! The more details you provide the more feedback we can give. + + +2. Next, the Express documentation team will respond with feedback on your submission. We read all submissions and try our best to always respond quickly with feedback. + - After you've received approval, *only then* should you start work or make any pull requests. + - If you really want to see you work merged into a super popular open source project, *and you do*, please always follow our process and open an issue first. + - __Please don't skip straight to a pull request unless you are totally sure your work is unique__. This is just because we never want anyone's time or hard work to go to waste on duplicated work. + +#### Step2: Get the Application Code Base + +After you've been approved, now you can clone the repo and get the code. +- `git clone https://github.com/expressjs/expressjs.com.git` + + +- These files render to html and make up the individual pages of the site. Most of the site's documentation text content is written in `md` files. +- Change these to make changes to individual pages' content/text or markup. +- Each translation has it's own complete set of pages, located under their respective language directories. Ex. English middleware page is located at `en > resources > middleware.md.` + +- These file are page components that make up the user interface and periphery structure. Ex. Header, Footer, etc. +- There are also markdown files here that are *included* within other larger files. Ex `api > en` holds the API Reference text content. +- Change these to make changes to page layouts or site-wide structures, or to change the API Reference documentation. +- Located mainly under `_includes` and `_layouts`. API markdown and text content are located under `_includes/api`. + +- These files make up the individual blog posts. If you want to contribute a blog post please +follow the specific instructions for [How to write a blog post.](https://expressjs.com/en/blog/write-post.html) +- Located under the `_posts` directory. + +- All css and js files are kept in `css` and `js` folders on the project root. + +#### Step3: Running the Application + + +1. __Run Locally__: This gets the local version of the application up and running on your machine. Follow our [Local Setup Guide](https://github.com/expressjs/expressjs.com?tab=readme-ov-file#local-setup) to use this option. + - This is the recommended option for moderate to complex work. +2. __Run using Deploy Preview__: Use this option if you don't want to bother with a local installation. Part of our continuous integration pipeline includes [Netlify Deploy Preview](https://docs.netlify.com/site-deploys/deploy-previews/). + - To use this you'll need to get your changes online - after you've made your first commit on your feature branch, make a *draft* pull request. + - After the build steps are complete, you'll have access to a __Deploy Preview__ tab that will run your changes on the web, rebuilding after each commit is pushed. + - After you are completely done your work and it's ready for review, remove the draft status on your pull request and submit your work. We will review it and respond. + +## Contributing translations + +#### Important Notice: We have paused all translation contributions. +> [!IMPORTANT] +> We are currently working toward a more streamlined translations workflow. As long as this notice is posted, we will _not_ be accepting any translation submissions. + +We highly encourage community translations! We no longer have professional translations, and we believe in the power of our community to provide accurate and helpful translations. + +- English (`en`) +- Spanish (`es`) +- French (`fr`) +- Italian (`it`) +- Indonesian (`id`) +- Japanese (`ja`) +- Korean (`ko`) +- Brazilian Portuguese (`pt-br`) +- Russian (`ru`) +- Slovak (`sk`) +- Thai (`th`) +- Turkish (`tr`) +- Ukrainian (`uk`) +- Uzbek (`uz`) +- Simplified Chinese (`zh-cn`) +- Traditional Chinese (`zh-tw`) + +### Adding New Full Site Translations + +If you find a translation is missing from the list you can create a new one. + + +1. Clone the [`expressjs.com`](https://github.com/expressjs/expressjs.com) repository. +2. 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. +3. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory. +4. Remove the link to 2.x docs from the "API Reference" menu. +5. Update the `lang` variable in the copied markdown files. +6. Update the `title` variable in the copied markdown files. +7. 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. +8. Create the announcement file for the language in the `_includes/` directory. +9. Make sure to append `/{{ page.lang }}` to all the links within the site. +10. Update the `CONTRIBUTING.md` and the `.github/workflows/translation.yml` files with the new language. + +### Adding Page and Section Translations + +Many site translations are still missing pages. To find which ones we need help with, you can [filter for merged PRs](https://github.com/expressjs/expressjs.com/pulls?q=is%3Apr+is%3Aclosed+label%3Arequires-translation-es) that include the tag for your language, such as `requires-translation-es` for requires Spanish translation. + +If you contribute a page or section translation, please reference the original PR. This helps the person merging your translation to remove the tag from the original PR. + + From e07a240214d90b26e0441e6aaaa0547f75587c3d Mon Sep 17 00:00:00 2001 From: Chris Del Date: Wed, 20 Nov 2024 12:08:43 -0600 Subject: [PATCH 11/13] remove front matter - remove over use of important - remove uz.css as it came back - removing CI commits - add HR line -Add GH NOTE tag and filter out --- .github/scripts/get-contributing.sh | 22 +++-- CONTRIBUTING.md | 7 +- css/uz.css | 17 ---- en/resources/contributing.md | 143 +--------------------------- 4 files changed, 18 insertions(+), 171 deletions(-) delete mode 100644 css/uz.css diff --git a/.github/scripts/get-contributing.sh b/.github/scripts/get-contributing.sh index 6bae4e4100..b1ca1ed2aa 100755 --- a/.github/scripts/get-contributing.sh +++ b/.github/scripts/get-contributing.sh @@ -1,6 +1,6 @@ #!/bin/bash -DEST="./en/resources/contributing.md" +DEST="../../en/resources/contributing.md" # This script replaces the contents of a section with the contents from # the annotated source address. @@ -14,11 +14,14 @@ local='' while IFS= read -r line; do # this section removes prev lines after file loads - src/load set to non-empty if [[ -n "$src" || -n "$local" ]]; then - # if line eq level - level is num of ##s - if [[ "$line" == "$level"'#'* || - # line not a header) - "$line" != '#'* ]]; then - continue + # line not a horitzontal rule hr + if [[ "$line" != "----"* ]]; then + # if line eq level - level is num of ##s + if [[ "$line" == "$level"'#'* || + # line not a header) + "$line" != '#'* ]]; then + continue + fi fi fi @@ -46,11 +49,12 @@ while IFS= read -r line; do cat "$local" | \ # remove the top 1# headers from cat'd file sed -En '/^##|^[^#]/,$p' | \ - # remove any ln starting w 'NOTE: lines' - sed -E '/^[NOTE:*]/d' | \ + # remove GH specific tags staring w '[!NOTE\] and next line + sed -E '/^>\[!NOTE\]*/{N;d}' | \ # remove any lines with 'Not the Express JS Framework' sed -E '/Not the Express JS Framework/I,$d' | \ - sed -E 's/> \[!IMPORTANT\]/> **IMORTANT:** /g' + # remove GH specific md tags + sed -E 's/> \[!IMPORTANT\]/> **IMPORTANT:** /g' echo elif [[ -n "$src" ]]; then echo diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba3a8e7fee..dab29d1c31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,8 @@ ### The Official Documentation of the Express Framework -**NOTE**: This is not the repo for Express JS. To contribute to the _[Express JS framework](https://github.com/expressjs/express)_ itself, [check this out](#were-the-express-js-frameworks-documenntation-team---not-the-express-js-framework). +>[!NOTE] +> This is not the repo for Express JS. To contribute to the _[Express JS framework](https://github.com/expressjs/express)_ itself, [check this out](#were-the-express-js-frameworks-documenntation-team---not-the-express-js-framework). If you want to contribute to [https://github.com/expressjs/expressjs.com](https://github.com/expressjs/expressjs.com), you're in the right place. @@ -28,7 +29,7 @@ If you see anything on the site that could use a tune-up, think about how to fix 3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. > [!IMPORTANT] -> All translation submissions are currently paused. See this [notice](#important-notice-we-have-paused-all-translation-contributions) for more information. +> All translation submissions are currently paused. See this [notice](#notice-we-have-paused-all-translation-contributions) for more information. - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. @@ -100,7 +101,7 @@ Now you'll need a way to see your changes, which means you'll need a running ver ## Contributing translations -#### Important Notice: We have paused all translation contributions. +#### Notice: We have paused all translation contributions. > [!IMPORTANT] > We are currently working toward a more streamlined translations workflow. As long as this notice is posted, we will _not_ be accepting any translation submissions. diff --git a/css/uz.css b/css/uz.css deleted file mode 100644 index 1b920cecdf..0000000000 --- a/css/uz.css +++ /dev/null @@ -1,17 +0,0 @@ -/* - Copyright (c) 2016 StrongLoop, IBM, and Express Contributors - License: MIT -*/ -/* For image callouts in writing-middleware.md */ - -#callout1 {top: 40px; } - -#callout2 {top: 60px;} - -#callout3 {top: 75px;} - -#callout4 {top: 145px;} - -#callout5 {top: 170px;} - -#callout6 {top: 195px;} diff --git a/en/resources/contributing.md b/en/resources/contributing.md index b1ae575940..d5171e7f9e 100644 --- a/en/resources/contributing.md +++ b/en/resources/contributing.md @@ -5,8 +5,6 @@ description: Find out how to contribute to Express.js, including guidelines for menu: resources lang: en redirect_from: "/resources/community.html" -title2: Contributing to Expressjs.com -sub-title: The official documentation for the Express framework. --- # Contributing to Express @@ -241,7 +239,6 @@ dissent. When the PR is merged, a TC member will add them to the proper GitHub/ ```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 @@ -378,145 +375,7 @@ We are currently working on a new version of the security model, the most update If you have suggestions on how this process could be improved please submit a pull request. +---- # Contributing to Expressjs.com {#expressjs-website-contributing} -### The Official Documentation of the Express Framework - - -If you want to contribute to [https://github.com/expressjs/expressjs.com](https://github.com/expressjs/expressjs.com), you're in the right place. - - -Whether you're a first time first time contributor or you're just looking for a refresher, visit our [Getting Started](#contributors-guide-to-getting-started) guide below to get up and running. - -#### Want to help but need some ideas? These are some of our most typical issue types: - -1. **Website Related**: -If you see anything on the site that could use a tune-up, think about how to fix it. - - - display or screen sizing problems - - mobile responsiveness issues - - missing or broken accessibility features - - website outages - - broken links - - page structure or user interface enhancements - - -2. **Content Related**: spelling errors, incorrect/outdated Express documentation, adding missing content. - - _We love any reports of typos. If you see one, fixing it is a great way to help_. - - -3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. -> [!IMPORTANT] -> All translation submissions are currently paused. See this [notice](#important-notice-we-have-paused-all-translation-contributions) for more information. - - - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. - -#### Want to work on a backlog issue? - -We often have bugs or enhancements that need work. You can find these on our repo [https://github.com/expressjs/expressjs.com/issues](https://github.com/expressjs/expressjs.com/issues). Check out the tags to find something that's a good match for you. - -#### Have an idea? Found a bug? - -If you've found a bug or a typo, or if you have an idea for an enhancement, please submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). You can do this by going to our [repo](https://github.com/expressjs/expressjs.com) and opening a "New Issue" under the **Issues** tab. If you submit it, we will respond. - -## Contributor's Guide to Getting Started - -If you want to learn about working on Expressjs.com, this is the right place. Follow the steps below to get started. - -#### TL;DR -1. Open an issue and get approval. -2. Make your pull request, and celebrate being a contributor. - - -#### Step1: Opening a New Issue -So, you've found a problem that you want to fix, or have a site enhancement you want to make. -1. The first step is to open an [issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). - - Give the issue a good title and be sure to fill in the description section, writing as much detail on your proposal as possible. - - Don't leave anything blank! The more details you provide the more feedback we can give. - - -2. Next, the Express documentation team will respond with feedback on your submission. We read all submissions and try our best to always respond quickly with feedback. - - After you've received approval, *only then* should you start work or make any pull requests. - - If you really want to see you work merged into a super popular open source project, *and you do*, please always follow our process and open an issue first. - - __Please don't skip straight to a pull request unless you are totally sure your work is unique__. This is just because we never want anyone's time or hard work to go to waste on duplicated work. - -#### Step2: Get the Application Code Base - -After you've been approved, now you can clone the repo and get the code. -- `git clone https://github.com/expressjs/expressjs.com.git` - - -- These files render to html and make up the individual pages of the site. Most of the site's documentation text content is written in `md` files. -- Change these to make changes to individual pages' content/text or markup. -- Each translation has it's own complete set of pages, located under their respective language directories. Ex. English middleware page is located at `en > resources > middleware.md.` - -- These file are page components that make up the user interface and periphery structure. Ex. Header, Footer, etc. -- There are also markdown files here that are *included* within other larger files. Ex `api > en` holds the API Reference text content. -- Change these to make changes to page layouts or site-wide structures, or to change the API Reference documentation. -- Located mainly under `_includes` and `_layouts`. API markdown and text content are located under `_includes/api`. - -- These files make up the individual blog posts. If you want to contribute a blog post please -follow the specific instructions for [How to write a blog post.](https://expressjs.com/en/blog/write-post.html) -- Located under the `_posts` directory. - -- All css and js files are kept in `css` and `js` folders on the project root. - -#### Step3: Running the Application - - -1. __Run Locally__: This gets the local version of the application up and running on your machine. Follow our [Local Setup Guide](https://github.com/expressjs/expressjs.com?tab=readme-ov-file#local-setup) to use this option. - - This is the recommended option for moderate to complex work. -2. __Run using Deploy Preview__: Use this option if you don't want to bother with a local installation. Part of our continuous integration pipeline includes [Netlify Deploy Preview](https://docs.netlify.com/site-deploys/deploy-previews/). - - To use this you'll need to get your changes online - after you've made your first commit on your feature branch, make a *draft* pull request. - - After the build steps are complete, you'll have access to a __Deploy Preview__ tab that will run your changes on the web, rebuilding after each commit is pushed. - - After you are completely done your work and it's ready for review, remove the draft status on your pull request and submit your work. We will review it and respond. - -## Contributing translations - -#### Important Notice: We have paused all translation contributions. -> [!IMPORTANT] -> We are currently working toward a more streamlined translations workflow. As long as this notice is posted, we will _not_ be accepting any translation submissions. - -We highly encourage community translations! We no longer have professional translations, and we believe in the power of our community to provide accurate and helpful translations. - -- English (`en`) -- Spanish (`es`) -- French (`fr`) -- Italian (`it`) -- Indonesian (`id`) -- Japanese (`ja`) -- Korean (`ko`) -- Brazilian Portuguese (`pt-br`) -- Russian (`ru`) -- Slovak (`sk`) -- Thai (`th`) -- Turkish (`tr`) -- Ukrainian (`uk`) -- Uzbek (`uz`) -- Simplified Chinese (`zh-cn`) -- Traditional Chinese (`zh-tw`) - -### Adding New Full Site Translations - -If you find a translation is missing from the list you can create a new one. - - -1. Clone the [`expressjs.com`](https://github.com/expressjs/expressjs.com) repository. -2. 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. -3. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory. -4. Remove the link to 2.x docs from the "API Reference" menu. -5. Update the `lang` variable in the copied markdown files. -6. Update the `title` variable in the copied markdown files. -7. 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. -8. Create the announcement file for the language in the `_includes/` directory. -9. Make sure to append `/{{ page.lang }}` to all the links within the site. -10. Update the `CONTRIBUTING.md` and the `.github/workflows/translation.yml` files with the new language. - -### Adding Page and Section Translations - -Many site translations are still missing pages. To find which ones we need help with, you can [filter for merged PRs](https://github.com/expressjs/expressjs.com/pulls?q=is%3Apr+is%3Aclosed+label%3Arequires-translation-es) that include the tag for your language, such as `requires-translation-es` for requires Spanish translation. - -If you contribute a page or section translation, please reference the original PR. This helps the person merging your translation to remove the tag from the original PR. - - From 9d535716e5153b9d51c7af34935901572ba509d2 Mon Sep 17 00:00:00 2001 From: Chris Del Date: Sat, 23 Nov 2024 14:49:34 -0600 Subject: [PATCH 12/13] Make requested lang changes - remove all "approval" language - add optional wording - make everything Express JS wording - remove italics as it not required - remove TLDR --- CONTRIBUTING.md | 47 +++++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dab29d1c31..6b69c41be3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Expressjs.com -### The Official Documentation of the Express Framework +### The Official Documentation of the Express JS Framework >[!NOTE] > This is not the repo for Express JS. To contribute to the _[Express JS framework](https://github.com/expressjs/express)_ itself, [check this out](#were-the-express-js-frameworks-documenntation-team---not-the-express-js-framework). @@ -23,51 +23,48 @@ If you see anything on the site that could use a tune-up, think about how to fix - page structure or user interface enhancements -2. **Content Related**: spelling errors, incorrect/outdated Express documentation, adding missing content. - - _We love any reports of typos. If you see one, fixing it is a great way to help_. +2. **Content Related**: spelling errors, incorrect/outdated Express JS documentation, adding missing content. + - We love any reports of typos. If you see one, fixing it is a great way to help. 3. **Translation Related**: spelling errors, incorrect/poorly translated words, adding new full site translations. > [!IMPORTANT] > All translation submissions are currently paused. See this [notice](#notice-we-have-paused-all-translation-contributions) for more information. - - _If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below_. + - If you want to do a full site translation, or just translate a single page, there's a section specifically related to [translations](#contributing-translations) below. #### Want to work on a backlog issue? -We often have bugs or enhancements that need work. You can find these on our repo [https://github.com/expressjs/expressjs.com/issues](https://github.com/expressjs/expressjs.com/issues). Check out the tags to find something that's a good match for you. +We often have bugs or enhancements that need work. You can find these under our repo's [Issues tab](https://github.com/expressjs/expressjs.com/issues). Check out the tags to find something that's a good match for you. #### Have an idea? Found a bug? -If you've found a bug or a typo, or if you have an idea for an enhancement, please submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). You can do this by going to our [repo](https://github.com/expressjs/expressjs.com) and opening a "New Issue" under the **Issues** tab. If you submit it, we will respond. +If you've found a bug or a typo, or if you have an idea for an enhancement, you can: +- Submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md) on our repo. Do this for larger proposals, or if you'd like to discuss or get feedback first. +- Make a [Github pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). If you have already done work and it's ready to go, feel free to send it our way. ## Contributor's Guide to Getting Started -If you want to learn about working on Expressjs.com, this is the right place. Follow the steps below to get started. +The steps below will guide you through the expressjs.com contribution process. -#### TL;DR -1. Open an issue and get approval. -2. Make your pull request, and celebrate being a contributor. - - -#### Step1: Opening a New Issue +#### Step1: (OPTIONAL) Opening a New Issue So, you've found a problem that you want to fix, or have a site enhancement you want to make. -1. The first step is to open an [issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md). - - Give the issue a good title and be sure to fill in the description section, writing as much detail on your proposal as possible. - - Don't leave anything blank! The more details you provide the more feedback we can give. - +1. If you want to get feedback or discuss, open a discussion [issue](https://github.com/expressjs/expressjs.com/issues/new/choose) prior to starting work. This is not required, but encouraged for larger proposals. + - While we highly encourage this step, it is only for submissions proposing significant change. It helps us to clarify and focus the work, and ensure it aligns with overall project priorities. + - For submissions proposing small minor improvements or corrections, this is not needed. You can skip this step. + - When opening an issue please give it title and fill in the description section. The more details you provide, the more feedback we can give. -2. Next, the Express documentation team will respond with feedback on your submission. We read all submissions and try our best to always respond quickly with feedback. - - After you've received approval, *only then* should you start work or make any pull requests. - - If you really want to see you work merged into a super popular open source project, *and you do*, please always follow our process and open an issue first. - - __Please don't skip straight to a pull request unless you are totally sure your work is unique__. This is just because we never want anyone's time or hard work to go to waste on duplicated work. +2. After receiving your issue the Express JS documentation team will respond with feedback. We read every submissions and always try to respond quickly with feedback. + - For submissions proposing significant change, we encourage you to follow the review process before starting work. #### Step2: Get the Application Code Base -After you've been approved, now you can clone the repo and get the code. +Clone the repo and get the code: - `git clone https://github.com/expressjs/expressjs.com.git` -This is a list of the main sections of the application, where most changes are likely to be made. This may help you identify where files you need to change live. +Now that you've got the code you're ready to start making your changes! + +But just in case you need a little extra explanation, this section outlines the main sections of the code base, where most changes are likely to be made. **Markdown Page Files**: - These files render to html and make up the individual pages of the site. Most of the site's documentation text content is written in `md` files. @@ -88,6 +85,8 @@ follow the specific instructions for [How to write a blog post.](https://express **CSS or Javascript** - All css and js files are kept in `css` and `js` folders on the project root. +The Express JS website is build using [Jeykyll](https://jekyllrb.com/) and is hosted on [Github Pages](https://pages.github.com/). + #### Step3: Running the Application @@ -97,7 +96,7 @@ Now you'll need a way to see your changes, which means you'll need a running ver 2. __Run using Deploy Preview__: Use this option if you don't want to bother with a local installation. Part of our continuous integration pipeline includes [Netlify Deploy Preview](https://docs.netlify.com/site-deploys/deploy-previews/). - To use this you'll need to get your changes online - after you've made your first commit on your feature branch, make a *draft* pull request. - After the build steps are complete, you'll have access to a __Deploy Preview__ tab that will run your changes on the web, rebuilding after each commit is pushed. - - After you are completely done your work and it's ready for review, remove the draft status on your pull request and submit your work. We will review it and respond. + - After you are completely done your work and it's ready for review, remove the draft status on your pull request and submit your work. ## Contributing translations From 34977ba4bf81919c8ae9c5d77d2a8c93633b616c Mon Sep 17 00:00:00 2001 From: Chris Del Date: Sat, 23 Nov 2024 14:55:49 -0600 Subject: [PATCH 13/13] Update CONTRIBUTING.md Small typo fixes --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b69c41be3..d9f8583b53 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ We often have bugs or enhancements that need work. You can find these under our #### Have an idea? Found a bug? If you've found a bug or a typo, or if you have an idea for an enhancement, you can: -- Submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new?assignees=&labels=&projects=&template=3other.md) on our repo. Do this for larger proposals, or if you'd like to discuss or get feedback first. +- Submit a [new issue](https://github.com/expressjs/expressjs.com/issues/new/choose) on our repo. Do this for larger proposals, or if you'd like to discuss or get feedback first. - Make a [Github pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). If you have already done work and it's ready to go, feel free to send it our way. ## Contributor's Guide to Getting Started @@ -52,9 +52,9 @@ So, you've found a problem that you want to fix, or have a site enhancement you 1. If you want to get feedback or discuss, open a discussion [issue](https://github.com/expressjs/expressjs.com/issues/new/choose) prior to starting work. This is not required, but encouraged for larger proposals. - While we highly encourage this step, it is only for submissions proposing significant change. It helps us to clarify and focus the work, and ensure it aligns with overall project priorities. - For submissions proposing small minor improvements or corrections, this is not needed. You can skip this step. - - When opening an issue please give it title and fill in the description section. The more details you provide, the more feedback we can give. + - When opening an issue please give it a title and fill in the description section. The more details you provide, the more feedback we can give. -2. After receiving your issue the Express JS documentation team will respond with feedback. We read every submissions and always try to respond quickly with feedback. +2. After receiving your issue the Express JS documentation team will respond with feedback. We read every submission and always try to respond quickly with feedback. - For submissions proposing significant change, we encourage you to follow the review process before starting work. #### Step2: Get the Application Code Base @@ -151,4 +151,4 @@ If you contribute a page or section translation, please reference the original P If you are looking for the repository for the **Express JS Framework**, you've hopefully noticed by now that you've come to the wrong place. This page is only for issues related to the this website: [https://expressjs.com](https://expressjs.com). -For more information on contributing to Express itself, check our out our [Contributing to Express](/{{ page.lang }}/resources/contributing.html) page. For anything else, visit the repository [https://github.com/expressjs/express](https://github.com/expressjs/express). \ No newline at end of file +For more information on contributing to Express itself, check our out our [Contributing to Express](/{{ page.lang }}/resources/contributing.html) page. For anything else, visit the repository [https://github.com/expressjs/express](https://github.com/expressjs/express).