Skip to content

Commit 3536239

Browse files
chrisdel101Chris Delchris delbjohansebascrandmck
authored
Contributing.md Enhancement (#1683)
Co-authored-by: Chris Del <[email protected]> Co-authored-by: chris del <[email protected]> Co-authored-by: Sebastian Beltran <[email protected]> Co-authored-by: Rand McKinney <[email protected]>
1 parent 8715a21 commit 3536239

File tree

4 files changed

+197
-39
lines changed

4 files changed

+197
-39
lines changed

‎.github/scripts/get-contributing.sh

Lines changed: 68 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,92 @@
11
#!/bin/bash
22

3-
DEST="../../en/resources/contributing.md"
3+
# This script replaces the contents of a section with the contents from the annotated source address or local file paths inside the DEST file.
44

5-
# This script replaces the contents of a section with the contents from
6-
# the annotated source address.
5+
# read contents of file into memory
6+
DEST="../../en/resources/contributing.md"
77

8+
# track the header level
89
level=''
10+
# tracks src for curl calls
911
src=''
10-
while IFS= read -r line; do
11-
if [[ -n "$src" ]] && [[ "$line" != '#'* || "$line" == "$level"'#'* ]]; then
12-
continue
12+
# tracks file paths for local file reads
13+
local=''
14+
while IFS= read -r line; do
15+
# REMOVE PREVIOUS CONTENT SECTION
16+
# if src or local tags are not empty
17+
if [[ -n "$src" || -n "$local" ]]; then
18+
# if current line not a horitzontal rule hr
19+
if [[ "$line" != "----"* ]]; then
20+
# if line == level -- level is num of ##
21+
if [[ "$line" == "$level"'#'* ||
22+
# line not a header line
23+
"$line" != '#'* ]]; then
24+
# skip line and rewrite over old content
25+
continue
26+
fi
27+
fi
1328
fi
1429

30+
# PRINT TO PAGE SECTION
1531
src=''
32+
local=''
33+
# if line is a header
1634
if [[ "$line" == '#'* ]]; then
17-
title=${line##*\#}
18-
level="${line:0:$((${#line} - ${#title}))}"
35+
# if header has (#id-of-link) or {#id-on-page} patterns
36+
if [[ $line =~ (\(\#.*\))\. || "$line" =~ \{\#.*\} ]]; then
37+
# isolate the matching part of line
38+
match=${BASH_REMATCH[0]}
39+
# remove match - leaving rest
40+
rest=${line//${match}}
41+
# remove any # symbols from start
42+
title_rest=${rest##*\#}
43+
# slice rest of line to get only level
44+
level="${rest:0:$((${#rest} - ${#title_rest}))}"
45+
else
46+
# any other headers -- these before SRC/LOCAL pages anchors
47+
header=${line##*\#}
48+
level="${line:0:$((${#line} - ${#header}))}"
49+
fi
50+
# if line is SRC anchor in read file
1951
elif [[ "$line" == '<!-- SRC:'* ]]; then
52+
# remove the first 10 chars
2053
src=${line:10}
54+
# % remove from end until after white space -- leaves src details
2155
src=${src% *}
22-
fi
23-
56+
# if line is LOCAL anchor in read file
57+
elif [[ "$line" == '<!-- LOCAL:'* ]]; then
58+
# remove the first 12 chars
59+
local=${line:12}
60+
# % remove from end until after white space -- leave local details
61+
local=${local% *}
62+
# leave only path to file
63+
local=${local#* }
64+
fi
65+
# prints line to the page
2466
echo "$line"
25-
26-
if [[ -n "$src" ]]; then
67+
68+
if [[ -n "$local" ]]; then
69+
# cat file -- outputs full contents of file at local path
70+
cat "$local" | \
71+
# remove the top 1# headers from cat'd file
72+
sed -En '/^##|^[^#]/,$p' | \
73+
# remove GH MD specific tags start w '[!NOTE\] + the following line
74+
sed -E '/^>\[!NOTE\]*/{N;d;}' | \
75+
# change GH specific MD IMPORTANT tags -> change into plain MD
76+
sed -E 's/> \[!IMPORTANT\]/> **IMPORTANT:** /g'
77+
echo
78+
elif [[ -n "$src" ]]; then
2779
echo
2880
path=${src#* }
2981
repo=${src% *}
3082
curl -s "https://raw.githubusercontent.com/${repo}/master/${path}" | \
83+
# if line is ## or not #
3184
sed -En '/^##|^[^#]/,$p' | \
85+
# add additional # every header
3286
sed 's/^#/&'"${level:1}"'/g' | \
87+
# format GH links when match
3388
sed -E 's/(\[[^]]*\])\(([^):#]*)\)/\1(https:\/\/github.com\/'"$(sed 's/\//\\\//g' <<< "$repo")"'\/blob\/master\/\2)/g'
3489
echo
3590
fi
91+
# read in dest file then write back to file
3692
done <<<"$(< $DEST)" > $DEST

‎CONTRIBUTING.md

Lines changed: 122 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,115 @@
1-
## Contributing to expressjs.com
1+
# Contributing to Expressjs.com
22

3-
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).
3+
### The Official Documentation of the Express JS Framework
44

5-
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.
5+
This is the contribution documentation for the [Expressjs.com](https://github.com/expressjs/expressjs.com) website.
66

7-
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;
8-
See [LICENSE.md](LICENSE.md) for the full license.
7+
>[!NOTE]
8+
> This is not the repo for Express JS framework. To contribute to the _[Express JS framework](https://github.com/expressjs/express_)_, check out the [Github repo contributing page](https://github.com/expressjs/express/blob/master/Contributing.md) or the website's [Contributing to Express](https://expressjs.com/en/resources/contributing.html) page.
99
10+
11+
#### Need some ideas? These are some typical issues.
12+
13+
1. **Website issues**:
14+
If you see anything on the site that could use a tune-up, think about how to fix it.
15+
16+
- Display or screen sizing problems
17+
- Mobile responsiveness issues
18+
- Missing or broken accessibility features
19+
- Website outages
20+
- Broken links
21+
- Page structure or user interface enhancements
22+
23+
24+
2. **Content Issues**:
25+
Fix anything related to site content or typos.
26+
- Spelling errors
27+
- Incorrect/outdated Express JS documentation
28+
- Missing content
29+
30+
31+
3. **Translation Issues**: Fix any translation errors or contribute new content.
32+
- Fix spelling errors
33+
- Fix incorrect/poorly translated words
34+
- Translate new content
35+
> [!IMPORTANT]
36+
> All translation submissions are currently paused. See this [notice](#notice-we-have-paused-all-translation-contributions) for more information.
37+
38+
- Check out the [Contributing translations](#contributing-translations) section below for a contributing guide.
39+
40+
#### Want to work on a backlog issue?
41+
42+
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.
43+
44+
#### Have an idea? Found a bug?
45+
46+
If you've found a bug or a typo, or if you have an idea for an enhancement, you can:
47+
- 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.
48+
- 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.
49+
50+
## Getting Started
51+
52+
The steps below will guide you through the Expressjs.com contribution process.
53+
54+
#### Step 1: (OPTIONAL) Open a New Issue
55+
So you've found a problem that you want to fix, or have a site enhancement you want to make.
56+
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.
57+
- 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.
58+
- For submissions proposing minor improvements or corrections, this is not needed. You can skip this step.
59+
- 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.
60+
61+
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.
62+
- For submissions proposing significant change, we encourage you to follow the review process before starting work.
63+
64+
#### Step 2: Get the Application Code Base
65+
66+
Clone the repo and get the code:
67+
68+
git clone https://github.com/expressjs/expressjs.com.git
69+
70+
After you've got the code you're ready to start making your changes!
71+
72+
But just in case you need a little extra explanation, this section below outlines the main sections of the code base, where most changes are likely to be made.
73+
74+
**Markdown Page Files**:
75+
- 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.
76+
- Change these to make changes to individual pages' content/text or markup.
77+
- Each language has its own complete set of pages, located under their respective language directories - all the Spanish markdown content is found in the `es` directory, for example.
78+
79+
**Includes Partials and Layout Templates**
80+
- `_includes` are partials that are imported and reused across multiple pages.
81+
- These are used to import text content for reuse across pages, such as the API documentation, e.g., `_includes > api > en > 5x`, which is included in every language.
82+
- These are used to include the page components that make up site-wide user interface and periphery structure, e.g., Header, Footer, etc.
83+
- `_layouts` are the templates used to wrap the site's individual pages.
84+
- These are used to display the structure of the site's periphery, such as the header and footer, and for injecting and displaying individual markdown pages inside the `content` tag.
85+
86+
**Blog Markdown Files**
87+
- These files make up the individual blog posts. If you want to contribute a blog post please
88+
follow the specific instructions for [How to write a blog post.](https://expressjs.com/en/blog/write-post.html)
89+
- Located under the `_posts` directory.
90+
91+
**CSS or Javascript**
92+
- All css and js files are kept in `css` and `js` folders on the project root.
93+
94+
The Express JS website is build using [Jeykyll](https://jekyllrb.com/) and is hosted on [Github Pages](https://pages.github.com/).
95+
96+
#### Step 3: Running the Application
97+
98+
99+
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.
100+
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.
101+
- This is the recommended option for moderate to complex work.
102+
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/).
103+
1. 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.
104+
2. 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.
105+
3. 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.
106+
10107
## Contributing translations
11108

109+
#### Notice: We have paused all translation contributions.
110+
> [!IMPORTANT]
111+
> 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.
112+
12113
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.
13114

14115
The documentation is translated into these languages:
@@ -29,27 +130,25 @@ The documentation is translated into these languages:
29130
- Simplified Chinese (`zh-cn`)
30131
- Traditional Chinese (`zh-tw`)
31132

32-
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`.
133+
### Adding New Full Site Translations
33134

34-
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.
135+
If you find a translation is missing from the list you can create a new one.
35136

137+
To translate Expressjs.com into a new language, follow these steps:
36138

37-
### Adding new translations
38-
39-
To contribute a translation into another language, following the procedure below.
40-
41-
Follow these steps:
42-
43-
0. Clone the [`expressjs.com` repository](https://github.com/expressjs/expressjs.com)
44-
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.
45-
2. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory.
46-
3. Remove the link to 2.x docs from the "API Reference" menu.
47-
4. Update the `lang` variable in the copied markdown files.
48-
5. Update the `title` variable in the copied markdown files.
49-
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.
50-
7. Create the announcement file for the language in the `_includes/` directory.
139+
1. Clone the [`expressjs.com`](https://github.com/expressjs/expressjs.com) repository.
140+
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.
141+
3. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory.
142+
4. Remove the link to 2.x docs from the "API Reference" menu.
143+
5. Update the `lang` variable in the copied markdown files.
144+
6. Update the `title` variable in the copied markdown files.
145+
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.
146+
8. Create the announcement file for the language in the `_includes/` directory.
51147
9. Make sure to append `/{{ page.lang }}` to all the links within the site.
52-
10. Update the `CONTRIBUTING.md` and the `.github/workflows/translation.yml` files with the new language
148+
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.
149+
150+
### Adding Page and Section Translations
53151

152+
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.
54153

55-
Thank you for your interest in contributing to expressjs.com. Your efforts help make our documentation accessible to everyone!
154+
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.

‎README.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -73,9 +73,7 @@ The default GitHub Pages syntax highlighting has been disabled in `_config.yml`
7373

7474
## Contributing
7575

76-
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.
77-
78-
Please see the [Contributors' Guide](CONTRIBUTING.md) for more information on contributing to the documentation, including information on contributing translations.
76+
Please see the [Contributors' Guide](CONTRIBUTING.md) for more information on contributing to the Express JS documentation, including information on contributing translations.
7977

8078
## Why use Jekyll instead of an Express-based solution?
8179

‎en/resources/contributing.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ redirect_from: "/resources/community.html"
99

1010
# Contributing to Express
1111

12+
### Looking to contribute to Expressjs.com? Click [here](#expressjs-website-contributing).
13+
1214
Express and the other projects in the [expressjs organization on GitHub](https://github.com/expressjs) are projects of the [OpenJs Foundation](https://openjsf.org/).
1315
These projects are governed under the general policies and guidelines of the Node.js Foundation along with the additional guidelines below.
1416

@@ -237,7 +239,6 @@ dissent. When the PR is merged, a TC member will add them to the proper GitHub/
237239

238240
```text
239241
By making a contribution to this project, I certify that:
240-
241242
(a) The contribution was created in whole or in part by me and I
242243
have the right to submit it under the open source license
243244
indicated in the file; or
@@ -374,3 +375,7 @@ We are currently working on a new version of the security model, the most update
374375
If you have suggestions on how this process could be improved please submit a
375376
pull request.
376377

378+
----
379+
# Contributing to Expressjs.com {#expressjs-website-contributing}
380+
381+
<!-- LOCAL: expressjs/expressjs.com ../../CONTRIBUTING.md -->

0 commit comments

Comments
 (0)