Skip to content

Commit

Permalink
doc: make contributing info more discoverable
Browse files Browse the repository at this point in the history
There are been several discussions in recent PRs about
the docs related to contributing not being very discoverable.
Move these docs from doc/guides/ to doc/contributing.

Signed-off-by: Michael Dawson <mdawson@devrus.com>

PR-URL: #41408
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Mary Marchini <oss@mmarchini.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
mhdawson committed Jan 18, 2022
1 parent 65910c0 commit a199387
Show file tree
Hide file tree
Showing 53 changed files with 58 additions and 60 deletions.
6 changes: 2 additions & 4 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,7 @@
/CODE_OF_CONDUCT.md @nodejs/tsc
/CONTRIBUTING.md @nodejs/tsc
/LICENSE @nodejs/tsc
/doc/guides/contributing/*.md @nodejs/tsc
/doc/guides/collaborator-guide.md @nodejs/tsc
/doc/guides/offboarding.md @nodejs/tsc
/doc/contributing/*.md @nodejs/tsc

# streams

Expand Down Expand Up @@ -88,7 +86,7 @@

/src/node_api* @nodejs/node-api
/src/js_native_api* @nodejs/node-api
/doc/guides/adding-new-napi-api.md @nodejs/node-api
/doc/contributing/adding-new-napi-api.md @nodejs/node-api
/doc/api/n-api.md @nodejs/node-api

# gyp
Expand Down
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Before submitting a pull request, please read
https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md.
Commit message formatting guidelines:
https://github.com/nodejs/node/blob/HEAD/doc/guides/contributing/pull-requests.md#commit-message-guidelines
https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines
For code changes:
1. Include tests for any bug fixes or new features.
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/auto-start-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ on:
# Runs every five minutes (fastest the scheduler can run). Five minutes is
# optimistic, it can take longer to run.
# To understand why `schedule` is used instead of other events, refer to
# ./doc/guides/commit-queue.md
# ./doc/contributing/commit-queue.md
- cron: "*/5 * * * *"

env:
Expand Down
26 changes: 13 additions & 13 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,28 @@
* [Pull Requests](#pull-requests)
* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin)

## [Code of Conduct](./doc/guides/contributing/code-of-conduct.md)
## [Code of Conduct](./doc/contributing/code-of-conduct.md)

The Node.js project has a
[Code of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md)
to which all contributors must adhere.

See [details on our policy on Code of Conduct](./doc/guides/contributing/code-of-conduct.md).
See [details on our policy on Code of Conduct](./doc/contributing/code-of-conduct.md).

## [Issues](./doc/guides/contributing/issues.md)
## [Issues](./doc/contributing/issues.md)

* [Asking for General Help](./doc/guides/contributing/issues.md#asking-for-general-help)
* [Discussing non-technical topics](./doc/guides/contributing/issues.md#discussing-non-technical-topics)
* [Submitting a Bug Report](./doc/guides/contributing/issues.md#submitting-a-bug-report)
* [Triaging a Bug Report](./doc/guides/contributing/issues.md#triaging-a-bug-report)
* [Asking for General Help](./doc/contributing/issues.md#asking-for-general-help)
* [Discussing non-technical topics](./doc/contributing/issues.md#discussing-non-technical-topics)
* [Submitting a Bug Report](./doc/contributing/issues.md#submitting-a-bug-report)
* [Triaging a Bug Report](./doc/contributing/issues.md#triaging-a-bug-report)

## [Pull Requests](./doc/guides/contributing/pull-requests.md)
## [Pull Requests](./doc/contributing/pull-requests.md)

* [Dependencies](./doc/guides/contributing/pull-requests.md#dependencies)
* [Setting up your local environment](./doc/guides/contributing/pull-requests.md#setting-up-your-local-environment)
* [The Process of Making Changes](./doc/guides/contributing/pull-requests.md#the-process-of-making-changes)
* [Reviewing Pull Requests](./doc/guides/contributing/pull-requests.md#reviewing-pull-requests)
* [Notes](./doc/guides/contributing/pull-requests.md#notes)
* [Dependencies](./doc/contributing/pull-requests.md#dependencies)
* [Setting up your local environment](./doc/contributing/pull-requests.md#setting-up-your-local-environment)
* [The Process of Making Changes](./doc/contributing/pull-requests.md#the-process-of-making-changes)
* [Reviewing Pull Requests](./doc/contributing/pull-requests.md#reviewing-pull-requests)
* [Notes](./doc/contributing/pull-requests.md#notes)

<a id="developers-certificate-of-origin"></a>

Expand Down
4 changes: 2 additions & 2 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Triagers are given the "Triage" GitHub role and have:
See:

* [List of triagers](./README.md#triagers)
* [A guide for triagers](./doc/guides/contributing/issues.md#triaging-a-bug-report)
* [A guide for triagers](./doc/contributing/issues.md#triaging-a-bug-report)

## Collaborators

Expand Down Expand Up @@ -54,7 +54,7 @@ result in collaborators removing their opposition.
See:

* [List of collaborators](./README.md#current-project-team-members)
* [A guide for collaborators](./doc/guides/collaborator-guide.md)
* [A guide for collaborators](./doc/contributing/collaborator-guide.md)

### Collaborator activities

Expand Down
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -997,14 +997,14 @@ endif
.PHONY: release-only
release-only: check-xz
@if [ "$(DISTTYPE)" = "release" ] && `grep -q REPLACEME doc/api/*.md`; then \
echo 'Please update REPLACEME tags in the following doc/api/*.md files (See doc/guides/releases.md):\n' ; \
echo 'Please update REPLACEME tags in the following doc/api/*.md files (See doc/contributing/releases.md):\n' ; \
REPLACEMES="$(shell grep -l REPLACEME doc/api/*.md)" ; \
echo "$$REPLACEMES\n" | tr " " "\n" ; \
exit 1 ; \
fi
@if [ "$(DISTTYPE)" = "release" ] && \
`grep -q DEP...X doc/api/deprecations.md`; then \
echo 'Please update DEP...X in doc/api/deprecations.md (See doc/guides/releases.md)' ; \
echo 'Please update DEP...X in doc/api/deprecations.md (See doc/contributing/releases.md)' ; \
exit 1 ; \
fi
@if [ "$(shell git status --porcelain | egrep -v '^\?\? ')" = "" ]; then \
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -635,7 +635,7 @@ For information about the governance of the Node.js project, see

<!--lint enable prohibited-strings-->

Collaborators follow the [Collaborator Guide](./doc/guides/collaborator-guide.md) in
Collaborators follow the [Collaborator Guide](./doc/contributing/collaborator-guide.md) in
maintaining the Node.js project.

### Triagers
Expand Down Expand Up @@ -741,6 +741,6 @@ license text.
[Contributing to the project]: CONTRIBUTING.md
[Node.js Website]: https://nodejs.org/
[OpenJS Foundation]: https://openjsf.org/
[Strategic initiatives]: doc/guides/strategic-initiatives.md
[Technical values and prioritization]: doc/guides/technical-values.md
[Strategic initiatives]: doc/contributing/strategic-initiatives.md
[Technical values and prioritization]: doc/contributing/technical-values.md
[Working Groups]: https://github.com/nodejs/TSC/blob/HEAD/WORKING_GROUPS.md
8 changes: 4 additions & 4 deletions benchmark/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ of different Node.js implementations and different ways of
writing JavaScript run by the built-in JavaScript engine.

For a detailed guide on how to write and run benchmarks in this
directory, see [the guide on benchmarks](../doc/guides/writing-and-running-benchmarks.md).
directory, see [the guide on benchmarks](../doc/contributing/writing-and-running-benchmarks.md).

## Table of Contents

Expand Down Expand Up @@ -77,17 +77,17 @@ writing benchmarks.

### `createBenchmark(fn, configs[, options])`

See [the guide on writing benchmarks](../doc/guides/writing-and-running-benchmarks.md#basics-of-a-benchmark).
See [the guide on writing benchmarks](../doc/contributing/writing-and-running-benchmarks.md#basics-of-a-benchmark).

### `default_http_benchmarker`

The default benchmarker used to run HTTP benchmarks.
See [the guide on writing HTTP benchmarks](../doc/guides/writing-and-running-benchmarks.md#creating-an-http-benchmark).
See [the guide on writing HTTP benchmarks](../doc/contributing/writing-and-running-benchmarks.md#creating-an-http-benchmark).

### `PORT`

The default port used to run HTTP benchmarks.
See [the guide on writing HTTP benchmarks](../doc/guides/writing-and-running-benchmarks.md#creating-an-http-benchmark).
See [the guide on writing HTTP benchmarks](../doc/contributing/writing-and-running-benchmarks.md#creating-an-http-benchmark).

### `sendResult(data)`

Expand Down
2 changes: 1 addition & 1 deletion deps/openssl/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,4 @@ Please refer [config/opensslconf_asm.h](config/opensslconf_asm.h) for details.

### Upgrading OpenSSL

Please refer to [maintaining-openssl](../../doc/guides/maintaining-openssl.md).
Please refer to [maintaining-openssl](../../doc/contributing/maintaining-openssl.md).
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -408,7 +408,7 @@ For pull requests introducing new core modules:
Node-API provides an ABI-stable API guaranteed for future Node.js versions.
Node-API additions call for unusual care and scrutiny. If a change adds to
`node_api.h`, `js_native_api.h`, `node_api_types.h`, or `js_native_api_types.h`,
consult [the relevant guide](https://github.com/nodejs/node/blob/HEAD/doc/guides/adding-new-napi-api.md).
consult [the relevant guide](https://github.com/nodejs/node/blob/HEAD/doc/contributing/adding-new-napi-api.md).

### Deprecations

Expand Down Expand Up @@ -558,7 +558,7 @@ $ git checkout master
```

Update the tree (assumes your repository is set up as detailed in
[CONTRIBUTING.md](./contributing/pull-requests.md#step-1-fork)):
[CONTRIBUTING.md](./pull-requests.md#step-1-fork)):

```text
$ git fetch upstream
Expand Down Expand Up @@ -925,7 +925,7 @@ need to be attached anymore, as only important bugfixes will be included.
[`--throw-deprecation`]: ../api/cli.md#--throw-deprecation
[`node-core-utils`]: https://github.com/nodejs/node-core-utils
[backporting guide]: backporting-to-release-lines.md
[commit message guidelines]: contributing/pull-requests.md#commit-message-guidelines
[commit message guidelines]: pull-requests.md#commit-message-guidelines
[commit-example]: https://github.com/nodejs/node/commit/b636ba8186
[commit-queue.md]: ./commit-queue.md
[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/
Expand Down
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -403,5 +403,5 @@ even `try` and `catch` **will** break.
[Run Time Type Information]: https://en.wikipedia.org/wiki/Run-time_type_information
[aliased_buffer.h]: https://github.com/nodejs/node/blob/HEAD/src/aliased_buffer.h#L12
[cppref_auto_ptr]: https://en.cppreference.com/w/cpp/memory/auto_ptr
[errors]: https://github.com/nodejs/node/blob/HEAD/doc/guides/using-internal-errors.md
[errors]: https://github.com/nodejs/node/blob/HEAD/doc/contributing/using-internal-errors.md
[without C++ exception handling]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_exceptions.html#intro.using.exception.no
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -62,5 +62,5 @@ Commit the changes with a message like
```text
deps: update c-ares to x.y.z
Updated as described in doc/guides/maintaining-c-ares.md.
Updated as described in doc/contributing/maintaining-c-ares.md.
```
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -32,5 +32,5 @@ Commit the changes with a message like
```text
deps: update zlib to upstream d7f3ca9
Updated as described in doc/guides/maintaining-zlib.md.
Updated as described in doc/contributing/maintaining-zlib.md.
```
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -137,8 +137,8 @@ added: REPLACEME
```

For contributing C++ code, you may want to look at the
[C++ Style Guide](../cpp-style-guide.md), as well as the
[README of `src/`](../../../src/README.md) for an overview of Node.js
[C++ Style Guide](cpp-style-guide.md), as well as the
[README of `src/`](../../src/README.md) for an overview of Node.js
C++ internals.

### Step 4: Commit
Expand Down Expand Up @@ -586,16 +586,16 @@ You can find the full list of supported subsystems in the
[nodejs/core-validate-commit][] repository.
More than one subsystem may be valid for any particular issue or pull request.

[Building guide]: ../../../BUILDING.md
[Building guide]: ../../BUILDING.md
[CI (Continuous Integration) test run]: #ci-testing
[Code of Conduct]: https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md
[Onboarding guide]: ../../../onboarding.md
[Onboarding guide]: ../../onboarding.md
[approved]: #getting-approvals-for-your-pull-request
[benchmark results]: ../writing-and-running-benchmarks.md
[collaborator guide]: ../collaborator-guide.md
[guide for writing tests in Node.js]: ../writing-tests.md
[benchmark results]: writing-and-running-benchmarks.md
[collaborator guide]: collaborator-guide.md
[guide for writing tests in Node.js]: writing-tests.md
[hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment
[https://ci.nodejs.org/]: https://ci.nodejs.org/
[nodejs/core-validate-commit]: https://github.com/nodejs/core-validate-commit/blob/main/lib/rules/subsystem.js
[pull request template]: https://raw.githubusercontent.com/nodejs/node/HEAD/.github/PULL_REQUEST_TEMPLATE.md
[running tests]: ../../../BUILDING.md#running-tests
[running tests]: ../../BUILDING.md#running-tests
2 changes: 1 addition & 1 deletion doc/guides/releases.md → doc/contributing/releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ When cherry-picking commits, if there are simple conflicts you can resolve
them. Otherwise, add the `backport-requested-vN.x` label to the original PR
and post a comment stating that it does not land cleanly and will require a
backport PR. You can refer the owner of the PR to the "[Backporting to Release
Lines](https://github.com/nodejs/node/blob/HEAD/doc/guides/backporting-to-release-lines.md)" guide.
Lines](https://github.com/nodejs/node/blob/HEAD/doc/contributing/backporting-to-release-lines.md)" guide.

If commits were cherry-picked in this step, check that the test still pass.

Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
10 changes: 5 additions & 5 deletions onboarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,15 +253,15 @@ needs to be pointed out separately during the onboarding.
access to the projects coverity project as outlined in [static-analysis][].

[Code of Conduct]: https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md
[Labels]: doc/guides/collaborator-guide.md#labels
[Landing pull requests]: doc/guides/collaborator-guide.md#landing-pull-requests
[Labels]: doc/contributing/collaborator-guide.md#labels
[Landing pull requests]: doc/contributing/collaborator-guide.md#landing-pull-requests
[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/
[`author-ready`]: doc/guides/collaborator-guide.md#author-ready-pull-requests
[`author-ready`]: doc/contributing/collaborator-guide.md#author-ready-pull-requests
[`core-validate-commit`]: https://github.com/nodejs/core-validate-commit
[`git-node`]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md
[`node-core-utils`]: https://github.com/nodejs/node-core-utils
[set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-github-credentials
[static-analysis]: doc/guides/static-analysis.md
[static-analysis]: doc/contributing/static-analysis.md
[two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/
[using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/
[who-to-cc]: doc/guides/collaborator-guide.md#who-to-cc-in-the-issue-tracker
[who-to-cc]: doc/contributing/collaborator-guide.md#who-to-cc-in-the-issue-tracker
2 changes: 1 addition & 1 deletion src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1024,7 +1024,7 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
}
```

[C++ coding style]: ../doc/guides/cpp-style-guide.md
[C++ coding style]: ../doc/contributing/cpp-style-guide.md
[Callback scopes]: #callback-scopes
[JavaScript value handles]: #js-handles
[N-API]: https://nodejs.org/api/n-api.html
Expand Down
2 changes: 1 addition & 1 deletion src/base_object.h
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ class BaseObject : public MemoryRetainer {
// class because it is used by src/node_postmortem_metadata.cc to calculate
// offsets and generate debug symbols for BaseObject, which assumes that the
// position of members in memory are predictable. For more information please
// refer to `doc/guides/node-postmortem-support.md`
// refer to `doc/contributing/node-postmortem-support.md`
friend int GenDebugSymbols();
friend class CleanupHookCallback;
template <typename T, bool kIsWeak>
Expand Down
2 changes: 1 addition & 1 deletion src/env.h
Original file line number Diff line number Diff line change
Expand Up @@ -1561,7 +1561,7 @@ class Environment : public MemoryRetainer {
// src/node_postmortem_metadata.cc to calculate offsets and generate debug
// symbols for Environment, which assumes that the position of members in
// memory are predictable. For more information please refer to
// `doc/guides/node-postmortem-support.md`
// `doc/contributing/node-postmortem-support.md`
friend int GenDebugSymbols();
HandleWrapQueue handle_wrap_queue_;
ReqWrapQueue req_wrap_queue_;
Expand Down
2 changes: 1 addition & 1 deletion src/handle_wrap.h
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ class HandleWrap : public AsyncWrap {
// class because it is used by src/node_postmortem_metadata.cc to calculate
// offsets and generate debug symbols for HandleWrap, which assumes that the
// position of members in memory are predictable. For more information please
// refer to `doc/guides/node-postmortem-support.md`
// refer to `doc/contributing/node-postmortem-support.md`
friend int GenDebugSymbols();
ListNode<HandleWrap> handle_wrap_queue_;
enum { kInitialized, kClosing, kClosed } state_;
Expand Down
2 changes: 1 addition & 1 deletion src/req_wrap.h
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ class ReqWrap : public AsyncWrap, public ReqWrapBase {
// members in memory are predictable. sizeof(req_) depends on the type of T,
// so req_wrap_queue_ would no longer be at a fixed offset if it came after
// req_. For more information please refer to
// `doc/guides/node-postmortem-support.md`
// `doc/contributing/node-postmortem-support.md`
T req_;
};

Expand Down
4 changes: 2 additions & 2 deletions test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
This directory contains code and data used to test the Node.js implementation.

For a detailed guide on how to write tests in this
directory, see [the guide on writing tests](../doc/guides/writing-tests.md).
directory, see [the guide on writing tests](../doc/contributing/writing-tests.md).

On how to run tests in this directory, see
[the contributing guide](../doc/guides/contributing/pull-requests.md#step-6-test).
[the contributing guide](../doc/contributing/pull-requests.md#step-6-test).

For the tests to run on Windows, be sure to clone Node.js source code with the
`autocrlf` git config flag set to true.
Expand Down
4 changes: 2 additions & 2 deletions tools/icu/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ Note:
## See Also

* [docs/guides/maintaining-icu.md](../../doc/guides/maintaining-icu.md) for
information on maintaining ICU in Node.js
* [docs/guides/maintaining-icu.md](../../doc/contributing/maintaining-icu.md)
for information on maintaining ICU in Node.js

* [docs/api/intl.md](../../doc/api/intl.md) for information on the
internationalization-related APIs in Node.js
Expand Down

0 comments on commit a199387

Please sign in to comment.