@cryptotaxi247 / documentation-1 / commits / b3e3ef9

README: reorganize README

Reorganize the README, splitting out contribution information into CONTRIBUTING.md. Add CODE_OF_CONDUCT.md and SECURITY.md.

Edward Thomson committed Apr 5, 2021 at 18:17 UTC b3e3ef921094a7c9be155f1718dc1758fb1bdc63
4 files changed +325 -204
CODE_OF_CONDUCT.md new
+81
@@ -0,0 +1,81 @@
1 +# Contributor Covenant Code of Conduct
2 +
3 +## Our Pledge
4 +
5 +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
6 +
7 +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
8 +
9 +## Our Standards
10 +
11 +Examples of behavior that contributes to a positive environment for our community include:
12 +
13 +* Demonstrating empathy and kindness toward other people
14 +* Being respectful of differing opinions, viewpoints, and experiences
15 +* Giving and gracefully accepting constructive feedback
16 +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
17 +* Focusing on what is best not just for us as individuals, but for the overall community
18 +
19 +Examples of unacceptable behavior include:
20 +
21 +* The use of sexualized language or imagery, and sexual attention or advances of any kind
22 +* Trolling, insulting or derogatory comments, and personal or political attacks
23 +* Public or private harassment
24 +* Publishing others' private information, such as a physical or email address, without their explicit permission
25 +* Contacting individual members, contributors, or leaders privately, outside designated community mechanisms, without their explicit permission
26 +* Other conduct which could reasonably be considered inappropriate in a professional setting
27 +
28 +## Enforcement Responsibilities
29 +
30 +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
31 +
32 +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
33 +
34 +## Scope
35 +
36 +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
37 +
38 +## Enforcement
39 +
40 +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at opensource@github.com. All complaints will be reviewed and investigated promptly and fairly.
41 +
42 +All community leaders are obligated to respect the privacy and security of the reporter of any incident.
43 +
44 +## Enforcement Guidelines
45 +
46 +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
47 +
48 +### 1. Correction
49 +
50 +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
51 +
52 +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
53 +
54 +### 2. Warning
55 +
56 +**Community Impact**: A violation through a single incident or series of actions.
57 +
58 +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
59 +
60 +### 3. Temporary Ban
61 +
62 +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
63 +
64 +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
65 +
66 +### 4. Permanent Ban
67 +
68 +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
69 +
70 +**Consequence**: A permanent ban from any sort of public interaction within the community.
71 +
72 +## Attribution
73 +
74 +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at <https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
75 +
76 +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
77 +
78 +[homepage]: https://www.contributor-covenant.org
79 +
80 +For answers to common questions about this code of conduct, see the FAQ at <https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
81 +
CONTRIBUTING.md new
+235
@@ -0,0 +1,235 @@
1 +# Contributing to the npm Documentation
2 +
3 +This is the documentation for
4 +[https://docs.npmjs.com/](https://docs.npmjs.com/). Do you want to
5 +contribute a change? Great!
6 +
7 +### Table of Contents
8 +
9 +* [Quick start](#quick-start)
10 +* [Running locally](#running-locally)
11 +* [Updating content](#updating-content)
12 +* [Navigation](#navigation)
13 +* [CLI](#cli)
14 +* [Deploying changes](#deploying-changes)
15 +* [Theme](#theme)
16 +
17 +## Quick start
18 +
19 +1. `npm install` to download gatsby, our theme, and the dependencies
20 +2. `npm run develop`: starts the test server at `http://localhost:8000`.
21 +3. Update the content - it's Mdx, which is like markdown - in the `content`
22 + directory.
23 +4. Review your content at `http://localhost:8000`. (Gatsby watches the
24 + filesystem and will reload your content changes immediately.)
25 +5. Once you're happy, commit it and open a pull request at
26 + https://github.com/npm/documentation.
27 +6. A CI workflow run will publish your PR to the staging documentation
28 + site at https://docs-staging.npmjs.com/.
29 +8. Once the content is reviewed, merge the pull request. That will
30 + [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml).
31 +
32 +## Running locally
33 +
34 +First, `npm install` the dependencies. This will install gatsby, et al.
35 +
36 +Next, `npm run develop` to start the test server to view your changes.
37 +The gatsby server will be started on port 8000. You can navigate to
38 +`http://localhost:8000` to view the site live.
39 +
40 +**Gatsby will watch your filesystem looking for updates.** Any content
41 +changes you make should be reflected in the site immediately.
42 +
43 +## Updating content
44 +
45 +### Documentation content
46 +
47 +The documentation content lives in the `content` directory, and is
48 +markdown. (Actually, [Mdx](https://mdxjs.com/), a sort of reactive
49 +markdown.)
50 +
51 +### Static content (images)
52 +
53 +Static content lives in the `static` directory. Since most of the
54 +static content is screenshots, you can use the `Screenshot` component
55 +to reference them, which is an extension of the `Img` component that
56 +is configured for the docs site. For example, an image living as
57 +`static/organizations/managing-temas/team-members.png` would be
58 +referenced as:
59 +
60 +```
61 +<Screenshot src="/organizations/managing-teams/team-members.png" alt="Screenshot of the team members button" />
62 +```
63 +
64 +(Note the `alt` tag, it is mandatory.)
65 +
66 +### "Shared" content
67 +
68 +There are various places where we want to share content between
69 +pages, to prevent copy-pasta. For example, we display a screenshot
70 +of the user login dialog repeatedly. Therefore this shared content
71 +is defined in `src/shared.js`, and includes a literal Mdx snippet.
72 +
73 +For example, `user-login` is defined with `text` and `image`
74 +properties:
75 +
76 +```js
77 +'user-login': {
78 + 'text': (<><Link href="https://www.npmjs.com/login">Log in</Link> to npm
79 + with your user account.</>),
80 + 'image': (<Screenshot src="/shared/user-login.png" alt="Screenshot of np
81 +m login dialog" />)
82 +},
83 +```
84 +
85 +Since Mdx is reactive, you can import the shared data at the top of the
86 +file, just beneath your frontmatter:
87 +
88 +```
89 +---
90 +title: Using shared content
91 +---
92 +import shared form '../../../src/shared.js'
93 +```
94 +
95 +And then reference the shared content within `<>`:
96 +
97 +```
98 +To login, <>{shared['user-login'].text}</>
99 +```
100 +
101 +### URLs
102 +
103 +Note that for backward compatibility reasons, the on-disk paths
104 +are not precisely identical to the URLs for the documentation.
105 +To keep URLs expressive but still short, intermediate directories
106 +are removed from a page's URL.
107 +
108 +You can see this navigating through the documentation hierarchy:
109 +if you visit the "Packages and modules" page, you'll navigate to
110 +`https://docs.npmjs.com/packages-and-modules`.
111 +
112 +There's then a folder beneath that, "Contributing packages to the
113 +registry", which is (sensibly) at
114 +`https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry`.
115 +
116 +You might (understandably) expect the page "Creating Node.js modules"
117 +to be URL-wise beneath `contributing-packages-to-the-registry`, but
118 +unfortunately, you would be wrong. To keep URLs short, the intermediate
119 +folder paths are removed from pages, so "Creating Node.js modules" becomes
120 +`https://docs.npmjs.com/creating-node-js-modules`.
121 +
122 +If you have only a URL and want to find where it lives on disk, you can
123 +consult the left-hand navigation on the site.
124 +
125 +<img width="353" alt="Screen Shot 2021-03-02 at 10 06 19" src="https://user-images.githubusercontent.com/1130014/109632522-04494980-7b3f-11eb-8b07-9e7bb992872f.png">
126 +
127 +You can also use `find` from within the `content` directory. For example:
128 +
129 +```
130 +find . -iname creating-node-js-modules\* -print
131 +```
132 +
133 +### Frontmatter
134 +
135 +The content pages should include
136 +[frontmatter](https://jekyllrb.com/docs/front-matter/).
137 +
138 +* `title`: the page's title (string); required
139 +* `redirect_from`: any URLs on the site that will be redirected to this page (array of strings)
140 +
141 +## Navigation
142 +
143 +The site's navigation (on the left-hand sidebar of the site) is controlled
144 +by `src/nav-base.yml`. If you add or remove a page from the site, you'll
145 +also want to add or remove it from the navigation configuration.
146 +
147 +Since the main documentation's navigation is combined with the CLI
148 +documentation's navigation to produce the overall navigation, you'll
149 +need to run the CLI update script (`cli/cli_import.js`) to combine
150 +the navigation. (More on that below.)
151 +
152 +**Todo:** we should isolate the navigational elements into their own
153 +script that runs as part of gatsby's `onPreBuild` phase.
154 +
155 +## CLI
156 +
157 +The documentation for the [npm cli](https://github.com/npm/cli) is not
158 +modified in this repository. Instead, the canonical location for it
159 +is in the [npm/cli](https://github.com/npm/cli) repository. Modifications
160 +to those files are automatically included here for completeness.
161 +
162 +**Pull requests to CLI documentation in this repository will be closed.**
163 +
164 +### Updating CLI Content
165 +
166 +Since the CLI documentation content lives in the [npm/cli
167 +repo](https://github.com/npm/cli), there is a [GitHub Actions
168 +workflow](https://github.com/npm/documentation/actions/workflows/update-cli.yml)
169 +that pulls documentation updates from the CLI into this repository.
170 +This is done nightly.
171 +
172 +This process can, of course, be done manually. This may be useful for
173 +editing its behavior or debugging.
174 +
175 +1. Review the configuration
176 + The `cli/releases.json` configures how the CLI documentation is
177 + included. It is an array of documentation versions, each having
178 + the following configuration:
179 +
180 + * `id`: A short identifier for the documentation version, eg
181 + `v6` or `v7`. This corresponds to a directory containing a
182 + version of the CLI repository (using a submodule). This will also
183 + be used as the output folder in the content.
184 + * `version`: The full semantic version number (eg `6.0.0`).
185 + * `title`: A long description of the version information. This will
186 + be used in the version picker,.
187 + * `branch`: The branch name for the version. This will be used to
188 + fetch the latest version of the documentation from GitHub.
189 +
190 +2. Fetch the latest content from the CLI repository
191 + Run `cli/cli_fetch.js` to download the submodules. This will
192 + initialize the submodules, fetch each one, and update them to
193 + the latest branch commit on the remote.
194 +
195 +3. Import the CLI's content into the main repository
196 + Run `cli/cli_import.js` to import the CLI's documentation from each
197 + directory. This will take the content in each submodule's
198 + `docs/content` directory, perform any necessary translations (like
199 + adding historical redirects) and putting it in this repository's
200 + `content` directory. In addition, it will take the `docs/nav.yml`
201 + and include it in this repository's navigation.
202 +
203 +## Reviewing changes
204 +
205 +The staging docs site (https://docs-staging.npmjs.com/) is published
206 +from a set of GitHub actions workflows. Since it is a separate site
207 +(with a separate GitHub Pages instance), the staging site lives in a
208 +[separate GitHub repository](https://github.com/npm/docs-staging).
209 +As a result when a pull request is opened in _this_ repository, we
210 +send a repository dispatch event to the `docs-staging` repository.
211 +
212 +A GitHub Actions workflow run in that repository will then build the
213 +pull request and publish the staging site for review.
214 +
215 +## Deploying changes
216 +
217 +The docs site (https://docs.npmjs.com/) is published from a
218 +[GitHub Actions workflow](https://github.com/npm/documentation/actions/workflows/publish.yml)
219 +on any push into the main branch. That means that the workflow for
220 +updating the site is:
221 +
222 +1. Make your changes locally, review them, commit them.
223 +2. Open a pull request for review
224 +3. Merge that pull request
225 +
226 +On step three, your changes will be published live! 🎉
227 +
228 +## Theme
229 +
230 +Much of the documentation's theme is separate.
231 +
232 +The gatsby theme used here is "doctornpm" - a variation of
233 +[doctocat](https://github.com/primer/doctocat) with some theme changes
234 +for npm's design language and additional components to support multiple
235 +versions of the CLI documentation.
README.md
+6 -204
@@ -5,15 +5,9 @@
5 This is the documentation for
6 [https://docs.npmjs.com/](https://docs.npmjs.com/).
7
8 -### Table of Contents
9 -
10 -* [Quick start](#quick-start)
11 -* [Running locally](#running-locally)
12 -* [Updating content](#updating-content)
13 -* [Navigation](#navigation)
14 -* [CLI](#cli)
15 -* [Deploying changes](#deploying-changes)
16 -* [Theme](#theme)
8 +[This repository](https://github.com/npm/documentation) contains the
9 +content for our documentation site, and the GitHub Actions workflows
10 +that generate the site itself.
11
12 ## Quick start
13
@@ -30,201 +24,7 @@ This is the documentation for
24 8. Once the content is reviewed, merge the pull request. That will
25 [deploy the site](https://github.com/npm/documentation/actions/workflows/publish.yml).
26
33 -## Running locally
34 -
35 -First, `npm install` the dependencies. This will install gatsby, et al.
36 -
37 -Next, `npm run develop` to start the test server to view your changes.
38 -The gatsby server will be started on port 8000. You can navigate to
39 -`http://localhost:8000` to view the site live.
40 -
41 -**Gatsby will watch your filesystem looking for updates.** Any content
42 -changes you make should be reflected in the site immediately.
43 -
44 -## Updating content
45 -
46 -### Documentation content
47 -
48 -The documentation content lives in the `content` directory, and is
49 -markdown. (Actually, [Mdx](https://mdxjs.com/), a sort of reactive
50 -markdown.)
51 -
52 -### Static content (images)
53 -
54 -Static content lives in the `static` directory. Since most of the
55 -static content is screenshots, you can use the `Screenshot` component
56 -to reference them, which is an extension of the `Img` component that
57 -is configured for the docs site. For example, an image living as
58 -`static/organizations/managing-temas/team-members.png` would be
59 -referenced as:
60 -
61 -```
62 -<Screenshot src="/organizations/managing-teams/team-members.png" alt="Screenshot of the team members button" />
63 -```
64 -
65 -(Note the `alt` tag, it is mandatory.)
66 -
67 -### "Shared" content
68 -
69 -There are various places where we want to share content between
70 -pages, to prevent copy-pasta. For example, we display a screenshot
71 -of the user login dialog repeatedly. Therefore this shared content
72 -is defined in `src/shared.js`, and includes a literal Mdx snippet.
73 -
74 -For example, `user-login` is defined with `text` and `image`
75 -properties:
76 -
77 -```js
78 -'user-login': {
79 - 'text': (<><Link href="https://www.npmjs.com/login">Log in</Link> to npm
80 - with your user account.</>),
81 - 'image': (<Screenshot src="/shared/user-login.png" alt="Screenshot of np
82 -m login dialog" />)
83 -},
84 -```
85 -
86 -Since Mdx is reactive, you can import the shared data at the top of the
87 -file, just beneath your frontmatter:
88 -
89 -```
90 ----
91 -title: Using shared content
92 ----
93 -import shared form '../../../src/shared.js'
94 -```
95 -
96 -And then reference the shared content within `<>`:
97 -
98 -```
99 -To login, <>{shared['user-login'].text}</>
100 -```
101 -
102 -### URLs
103 -
104 -Note that for backward compatibility reasons, the on-disk paths
105 -are not precisely identical to the URLs for the documentation.
106 -To keep URLs expressive but still short, intermediate directories
107 -are removed from a page's URL.
108 -
109 -You can see this navigating through the documentation hierarchy:
110 -if you visit the "Packages and modules" page, you'll navigate to
111 -`https://docs.npmjs.com/packages-and-modules`.
112 -
113 -There's then a folder beneath that, "Contributing packages to the
114 -registry", which is (sensibly) at
115 -`https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry`.
116 -
117 -You might (understandably) expect the page "Creating Node.js modules"
118 -to be URL-wise beneath `contributing-packages-to-the-registry`, but
119 -unfortunately, you would be wrong. To keep URLs short, the intermediate
120 -folder paths are removed from pages, so "Creating Node.js modules" becomes
121 -`https://docs.npmjs.com/creating-node-js-modules`.
122 -
123 -If you have only a URL and want to find where it lives on disk, you can
124 -consult the left-hand navigation on the site.
125 -
126 -<img width="353" alt="Screen Shot 2021-03-02 at 10 06 19" src="https://user-images.githubusercontent.com/1130014/109632522-04494980-7b3f-11eb-8b07-9e7bb992872f.png">
127 -
128 -You can also use `find` from within the `content` directory. For example:
129 -
130 -```
131 -find . -iname creating-node-js-modules\* -print
132 -```
133 -
134 -### Frontmatter
135 -
136 -The content pages should include
137 -[frontmatter](https://jekyllrb.com/docs/front-matter/).
138 -
139 -* `title`: the page's title (string); required
140 -* `redirect_from`: any URLs on the site that will be redirected to this page (array of strings)
141 -
142 -## Navigation
143 -
144 -The site's navigation (on the left-hand sidebar of the site) is controlled
145 -by `src/nav-base.yml`. If you add or remove a page from the site, you'll
146 -also want to add or remove it from the navigation configuration.
147 -
148 -Since the main documentation's navigation is combined with the CLI
149 -documentation's navigation to produce the overall navigation, you'll
150 -need to run the CLI update script (`cli/cli_import.js`) to combine
151 -the navigation. (More on that below.)
152 -
153 -**Todo:** we should isolate the navigational elements into their own
154 -script that runs as part of gatsby's `onPreBuild` phase.
155 -
156 -## CLI
157 -
158 -The documentation for the [npm cli](https://github.com/npm/cli) is not
159 -modified in this repository. Instead, the canonical location for it
160 -is in the [npm/cli](https://github.com/npm/cli) repository. Modifications
161 -to those files are automatically included here for completeness.
162 -
163 -**Pull requests to CLI documentation in this repository will be closed.**
164 -
165 -### Updating CLI Content
166 -
167 -Since the CLI documentation content lives in the [npm/cli
168 -repo](https://github.com/npm/cli), there is a [GitHub Actions
169 -workflow](https://github.com/npm/documentation/actions/workflows/update-cli.yml)
170 -that pulls documentation updates from the CLI into this repository.
171 -This is done nightly.
172 -
173 -This process can, of course, be done manually. This may be useful for
174 -editing its behavior or debugging.
175 -
176 -1. Review the configuration
177 - The `cli/releases.json` configures how the CLI documentation is
178 - included. It is an array of documentation versions, each having
179 - the following configuration:
180 -
181 - * `id`: A short identifier for the documentation version, eg
182 - `v6` or `v7`. This corresponds to a directory containing a
183 - version of the CLI repository (using a submodule). This will also
184 - be used as the output folder in the content.
185 - * `version`: The full semantic version number (eg `6.0.0`).
186 - * `title`: A long description of the version information. This will
187 - be used in the version picker,.
188 - * `branch`: The branch name for the version. This will be used to
189 - fetch the latest version of the documentation from GitHub.
190 -
191 -2. Fetch the latest content from the CLI repository
192 - Run `cli/cli_fetch.js` to download the submodules. This will
193 - initialize the submodules, fetch each one, and update them to
194 - the latest branch commit on the remote.
195 -
196 -3. Import the CLI's content into the main repository
197 - Run `cli/cli_import.js` to import the CLI's documentation from each
198 - directory. This will take the content in each submodule's
199 - `docs/content` directory, perform any necessary translations (like
200 - adding historical redirects) and putting it in this repository's
201 - `content` directory. In addition, it will take the `docs/nav.yml`
202 - and include it in this repository's navigation.
203 -
204 -## Reviewing changes
205 -
206 -The staging docs site (https://docs-staging.npmjs.com/) is published
207 -from a set of GitHub actions workflows. Since it is a separate site
208 -(with a separate GitHub Pages instance), the staging site lives in a
209 -[separate GitHub repository](https://github.com/npm/docs-staging).
210 -As a result when a pull request is opened in _this_ repository, we
211 -send a repository dispatch event to the `docs-staging` repository.
212 -
213 -A GitHub Actions workflow run in that repository will then build the
214 -pull request and publish the staging site for review.
215 -
216 -## Deploying changes
217 -
218 -The docs site (https://docs.npmjs.com/) is published from a
219 -[GitHub Actions workflow](https://github.com/npm/documentation/actions/workflows/publish.yml)
220 -on any push into the main branch. That means that the workflow for
221 -updating the site is:
222 -
223 -1. Make your changes locally, review them, commit them.
224 -2. Open a pull request for review
225 -3. Merge that pull request
226 -
227 -On step three, your changes will be published live! 🎉
27 +Do you want to know more? Check out our [contributing guide](CONTRIBUTING.md).
28
29 ## Theme
30
@@ -238,3 +38,5 @@ versions of the CLI documentation.
38 The npm product documentation in the assets, content, and data folders are licensed under a [CC-BY license](LICENSE).
39
40 All other code in this repository is licensed under a [MIT license](LICENSE-CODE).
41 +
42 +When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).
SECURITY.md new
+3
@@ -0,0 +1,3 @@
1 +If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
2 +
3 +Thanks for helping make GitHub Actions safe for everyone.