Skip to content

docs: fix typos and grammar in guidelines #644

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Avicennasis wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix typos and grammar in guidelines #644

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/DEPRECATE-GUIDELINES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Some criteria to determine if it's unmaintained:
If you are using a package that meets your requirements but you found issues or need enhancements, then these are some actions you can follow:

- Note the deprecation messages during `npm install` and follow the instruction if the message offered any.
- Check the package's npm page at `https://www.npmjs.com/package/<package-name>`. ie: <https://www.npmjs.com/package/express>
- Check the package's npm page at `https://www.npmjs.com/package/<package-name>`. i.e.: <https://www.npmjs.com/package/express>
- Check the "last publish" date and versions history to get a sense of its latest activity. Note that you may want to `npm show $package time` to see all the published versions and times, regardless of their dist-tag setting.
- Check if its `package.json` has a `support` field that indicates its support status.
- Open the "repository" link if it has one to view development activities (you can run `npm repo $package` to do this as well)
Expand All @@ -60,7 +60,7 @@ When you've opened the package's repo, to further check development activities:
- if npm audit identified vulnerabilities that are critical
- if package fails to install/build for an LTS release of node.js

- Check last activity on github issues and PRs. If there're no responses within some reasonable time to high priority issues or PRs, then consider the package as an unmaintained candidate.
- Check last activity on github issues and PRs. If there are no responses within some reasonable time to high priority issues or PRs, then consider the package as an unmaintained candidate.

#### Taking Further Actions

Expand All @@ -84,11 +84,11 @@ If you own a package and you want to stop maintaining it, then please help your
#### `npm deprecate` command

- npm has the "deprecate" command, you can utilize this.
- You can use semvers to deprecate a range. ie: `npm deprecate package@^1.0.0`
- You can use semvers to deprecate a range. i.e.: `npm deprecate package@^1.0.0`
- deprecate your latest version with a message that includes `"abandoned and unmaintained"`.
- It allows updating the message so you can change it later - verified as of 02/05/2019
- It can be undone by setting an empty message.
- ie: `npm deprecate package@1.0.0 ""`
- i.e.: `npm deprecate package@1.0.0 ""`
- Please consider marking an old version with critical issues or vulnerabilities as deprecated.

#### Mark abandoned/unmaintained
Expand All @@ -106,6 +106,6 @@ If you own a package and you want to stop maintaining it, then please help your

### Further Ideas and Tools

There are some ongoing discussion related to npm to make managing unmaintained packages easier.
There are some ongoing discussions related to npm to make managing unmaintained packages easier.

- Package override RFC https://github.com/aeschright/rfcs/blob/ca127d7c5fb7ecde534172d771351c0b8f819e79/accepted/0009-package-overrides.md
4 changes: 2 additions & 2 deletions docs/PUBLISH-GUIDELINES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ These guidelines exist to help package owners with some practices on managing pa
| publish config | [`publishConfig`] | Helpful if you need to publish to a different registry |
| publish package | [`npm publish`] | Actually publish the package |
| search/view published packages | [public registry] | [for example](https://www.npmjs.com/package/npm) |
| filter publish files | [`.npmignore`] or [`files`] | Use one base on your preference |
| filter publish files | [`.npmignore`] or [`files`] | Use one based on your preference |

### `.npmignore` or `files`

[npm] has default ignore rules and loads from `.gitignore` but it also offer two methods for you to keep your published packages tidy.
[npm] has default ignore rules and loads from `.gitignore` but it also offers two methods for you to keep your published packages tidy.

- blacklisting - specifying ignore files in `.npmignore`
- whitelisting - specifying files you only want to publish with `files` in your `package.json`.
Expand Down
6 changes: 3 additions & 3 deletions docs/governance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ As a project grows and contributions and activity start to increase, establishin
The aim of this document is to provide thoughts and recommendations to project maintainers for ways they can organize, document, and ultimately establish a Governance model that can be applied to their own project's needs.

## Vision
It is always helpful to include a section that clearly states the solution space / objectives of the project. This helps introduce the overarching vision of the project and help contextualize all further decision making. (technical or otherwise). Articulating the "why" of the project helps ensure maintainers and contributors alike are aligned on the direction of the project as so is a good candidate to put first.
It is always helpful to include a section that clearly states the solution space / objectives of the project. This helps introduce the overarching vision of the project and help contextualize all further decision making (technical or otherwise). Articulating the "why" of the project helps ensure maintainers and contributors alike are aligned on the direction of the project as so is a good candidate to put first.

## Team Organization

Expand All @@ -26,7 +26,7 @@ This is helpful for maintainers because they wouldn't have to clone a fork to te
> _As with owners and maintainers, enumerating the privileges and permissions of this group would also be recommended._

## Project Organization
There can be different models for how the project is structured / distributed and how the team is organized. This may the case with projects that use a monorepo structure or have a plugin like architecture, and are often building on top of a "core" or "cli" base package (`peerDependency` model). As projects expand horizontally and vertically, delegating maintainers to oversee sections of code or packages in your project can help with scaling communication and ownership, in particular in regards to issue triage and PR reviews. In addition, this helps build up subject matter expertise.
There can be different models for how the project is structured / distributed and how the team is organized. This may be the case with projects that use a monorepo structure or have a plugin like architecture, and are often building on top of a "core" or "cli" base package (`peerDependency` model). As projects expand horizontally and vertically, delegating maintainers to oversee sections of code or packages in your project can help with scaling communication and ownership, in particular in regards to issue triage and PR reviews. In addition, this helps build up subject matter expertise.

If your project groups multiple related packages (e.g. _transforms_, _middleware_, _plugins_, etc), consider how to govern those projects as they fan outwards, in particular when it comes to managing breaking changes, new APIs, and how that all cascades downstream to the users of the core package.

Expand All @@ -36,7 +36,7 @@ If your project groups multiple related packages (e.g. _transforms_, _middleware
## Technical Organization

### Code Quality
If the project has a preferred style guide, coding conventions, or other general rules around code quality, documenting those can be a good courtesy to those first time contributors to your project. This can help prepare contributions for such "housekeeping" tasks like minding the projects linting and formatting rules, expectations around writing unit test, or necessity around writing / updating documentation.
If the project has a preferred style guide, coding conventions, or other general rules around code quality, documenting those can be a good courtesy to those first time contributors to your project. This can help prepare contributions for such "housekeeping" tasks like minding the projects linting and formatting rules, expectations around writing unit tests, or necessity around writing / updating documentation.

### RFC Process
It's often good to segment off, or flag certain issues as `RFC` in particular to communicate important changes, potentially breaking, that are deserving of deeper conversation and analysis. Standing for [_"Request for Comment"_](https://en.wikipedia.org/wiki/Request_for_Comments), it is a good way to initiate high level changes to the project that can be set aside and reviewed periodically by the maintainers, or can be used by the maintainers to communicate back outwards to the community.
Expand Down