From f754aa362e84596a484ada490ea491f5920d69ff Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Tue, 20 Feb 2018 20:38:27 +0800 Subject: [PATCH 1/6] docs: move the travis integration guide from the automation repo --- enable-travis-under-nodejs.md | 81 +++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 enable-travis-under-nodejs.md diff --git a/enable-travis-under-nodejs.md b/enable-travis-under-nodejs.md new file mode 100644 index 00000000..c281eb24 --- /dev/null +++ b/enable-travis-under-nodejs.md @@ -0,0 +1,81 @@ +# How to enable Travis in a repository under the Node.js GitHub organization + +Since we don't allow third-party access to the Node.js GitHub organization +except our own bots, when a repository is transferred into the Node.js +foundation, Travis won't be able to update the build status of pull requests +automatically. Instead, we need to use our own GitHub bot to pull the status +from Travis and send the update in GitHub. This is what needs to be done: + +### Step 1: Travis setup + +Make sure Travis can listen to the push and pull request events of the +repository. Go to "Settings -> Integrations & services" page of the +repository. If Travis has been integrated with the repository before, +then it should be listed under "Services". If not, click on the dropdown +"Add service", and search for Travis to add it. + +The service does not really have to be configured to enable Travis. All of the +following configurations work: + +* User and Token configured as someone who is not "nodejs", and Domain is + blank +* User and Token left blank, Domain is `notify.travis-ci.org` +* User and Token configured as someone who is not "nodejs", Domain is + `notify.travis-ci.org` +* User, Token, Domain all left blank + +If `https://travis-ci.org/nodejs/{reponame}` starts building new pull requests +or pull request updates in the repository after the service is enabled, then +the Travis end is set up. + +### Step 2: add the bot to your team + +Go to the "Settings -> Collaborators & teams" page of the repository, add +`@nodejs-github-bot`, or the `@nodejs/bots` team to the collaborators of the +repository, so that the GitHub bot account has write access to it. If there +are 404 responses in the logs of build status updates sent from the bot, it +usually means the bot is not granted write access to the repository. + +### Step3: add the webhook for the bot + +On the "Settings -> Webhooks" page, add a new webhook for the bot: + +* Payload URL: `http://github-bot.nodejs.org:3333/hooks/github` +* Content type: `application/json` +* Secret: can be obtained in the https://github.com/nodejs/secrets repository, + or ask someone from the build working group to add the webhook for you. +* In "Which events would you like to trigger this webhook?", select "Let me + select individual events.", check "Push" and "Pull Request". +* Finally, check "Active" and save the webhook. GitHub will send a test + payload to the bot, if it comes back green, the bot is set up with the + repository. + +### Step 4: update the bot + +Open a pull request to https://github.com/nodejs/github-bot, adding the +repository to the `enabledRepos` in +https://github.com/nodejs/github-bot/blob/master/scripts/display-travis-status.js, +so the bot will not ignore the events from your repository and start sending +updates. + +### How it works + +The bot works like this: + +1. When a pull request is opened or updated, GitHub will send an event to both + Travis (configured in step 1) and the bot (step 3). +2. Travis will start the build, and the bot will start polling Travis + for build status (this requires step 4 otherwise the bot would ignore the + event). +3. When the bot finds the build matching the last commit in the PR, it + will update the build status of that PR as "pending" (this update requires + step 2). +4. When a poll comes back as a successful build, the bot will update the + build status as "success". + +### Aside + +If the transferred project is used across different platforms, consider +transferring the testing to the Node.js build infrastructure as well, so that +it can be tested across the platforms supported by Node.js. Open an issue in +https://github.com/nodejs/build for help getting the transfer done. From 2df2f4407f80ed0f524eb3be1c9edec23380b4f6 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Tue, 20 Feb 2018 20:38:38 +0800 Subject: [PATCH 2/6] docs: move the npm management doc from the build repo --- npm-management.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 npm-management.md diff --git a/npm-management.md b/npm-management.md new file mode 100644 index 00000000..d813735c --- /dev/null +++ b/npm-management.md @@ -0,0 +1,41 @@ +# NPM Management + +We have a number of modules under the Node.js Foundation including: + +* [citgm](https://github.com/nodejs/citgm) +* [llnode](https://github.com/nodejs/llnode) +* [node-gyp](https://github.com/nodejs/node-gyp) +* [node-inspect](https://github.com/nodejs/node-inspect) +* [node-report](https://github.com/nodejs/node-report) + +We need to make sure that we have continuity in terms of being able to publish +and update these modules. + +We have decided to manage these modules as follows: + +* Create a user called [`nodejs-foundation`][] who we always add as one of the + collaborators with admin rights and for which the password is maintained by + the build workgroup. +* We would then add individuals as collaborators who can also publish. + Generally, a module push will be done by the additional collaborators. + The `nodejs-foundation` user is intended to be used as a backup as opposed + to being part of the regular publishing flow. +* In the cases where collaborators other than `nodejs-foundation` + cease to be active, the build workgroup would provide continuity by using the + `node-foundation` user to add additional collaborators who would have the + ability to push the module. The `node-foundation` user could also be used to + remove collaborators if that was ever necessary. +* The purpose of the `nodejs-foundation` user is not to enable Build + Workgroup members to publish npm modules, that should be left to the + module collaborators. + +This approach is consistent with how npm modules have been managed by a number +of the companies who are foundation members and reports are that it has worked +well. + +The credentials required for the `nodejs-foundation` user are maintained in +encrypted form in the [secrets repo][]. + + +[`nodejs-foundation`]: https://www.npmjs.com/~nodejs-foundation +[secrets repo]: https://github.com/nodejs/secrets/tree/master/test/test_credentials.md From 7f8317babb35cfd507ae895b119dc039b714a3f7 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Tue, 20 Feb 2018 20:38:55 +0800 Subject: [PATCH 3/6] docs: add guide on transferring repositories into the organization --- transfer-repo-into-the-org.md | 75 +++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 transfer-repo-into-the-org.md diff --git a/transfer-repo-into-the-org.md b/transfer-repo-into-the-org.md new file mode 100644 index 00000000..2850c648 --- /dev/null +++ b/transfer-repo-into-the-org.md @@ -0,0 +1,75 @@ +# Transferring an existing repository into the organization + +## Step 1. Get the repository ready + +Ideally, the repository should have the following documents in place: + +- `CODE_OF_CONDUCT.md`: it can be a reference to + [the Node.js Code of Conduct][coc]. +- `CONTRIBUTING.md`: if there isn't one already, [the contributing guide][] + of Node.js core could be a good example. Consider including the Developer's + Certificate of Origin section in the document to avoid potential copyright + conflicts. +- `LICENSE`, or other kind of documents that describe the license of + the project. +- `README.md` + +## Step 2. Open an issue in the admin repository + +The people opening the issue should be a member of the Node.js organization, +so they can ping the relevant GitHub teams to discuss about the request. +If the person who want to initiate the request is not a member, they could ask +an existing member to open the issue, or request to join the organization. + +Go to [the issue tracker of the Node.js admin repository][], open an issue +to request moving the repository into the organization. The issue should include: + +- The owner and the name of the repository, and a link to it. +- What the repository is for, why it should be transferred into the organization. +- Mentions of `@nodejs/community-committee` and `@nodejs/tsc` so the Community + Committee and the Technical Steering Committee members can be notified about + the request and weigh in. + +See the [Node.js GitHub Organization Management Policy][] on how the request +are approved. + +## Step 3. Transfer the repository + +When the request is approved, the owner of the repository can start transferring +the repository into the Node.js GitHub organization. The person can be made a +member of the Node.js GitHub organization so they have the necessary permissions +to complete the transfer. + +See [GitHub's documentation on transferring repos][] on how to perform the +necessary actions. + +## Step 4. Manage releases + +If the transferred repository has one or more associated npm packages for releases, +[the Node.js foundation npm account](https://www.npmjs.com/~nodejs-foundation) +should be added to the list of the npm collaborators of the packages. The account +is managed by the Node.js Build Working Group and only serves as a safety net. +The releases should still by done by the original releasers. + +See [NPM Management](./npm-management.md) on more about the Node.js foundation +npm account. + +## Step 5. Fix integrations and Webhooks + +If the repository has previously configured external integrations and webhooks +(for example, the Travis CI), do know that we do not allow third-party +applications integrated into the organization. It's fine to keep the +per-repository webhooks or add new ones, but a lot of external services require +permissions to read the list of repositories of the organization in addition +to webhooks, so the previous integrations may stop working once the repository +is transferred. + +It is possible to bring Travis integration back using the Node.js GitHub bot. +See the guide on [enabling Travis in a repository under the Node.js GitHub organization][]. + +[coc]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md +[GitHub's documentation on transferring repos]: https://help.github.com/articles/about-repository-transfers/ +[Node.js GitHub Organization Management Policy]: https://github.com/nodejs/TSC/blob/master/GitHub-Org-Management-Policy.md#repositories +[the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md +[the issue tracker of the Node.js admin repository]: https://github.com/nodejs/admin/issues +[enabling Travis in a repository under the Node.js GitHub organization]: ./enable-travis-under-nodejs.md \ No newline at end of file From 6215b27cb3f4f5e0dac802af20022ed4b86c498a Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Fri, 7 Dec 2018 11:01:05 +0800 Subject: [PATCH 4/6] remove outdated travis guide --- enable-travis-under-nodejs.md | 81 ----------------------------------- transfer-repo-into-the-org.md | 14 ------ 2 files changed, 95 deletions(-) delete mode 100644 enable-travis-under-nodejs.md diff --git a/enable-travis-under-nodejs.md b/enable-travis-under-nodejs.md deleted file mode 100644 index c281eb24..00000000 --- a/enable-travis-under-nodejs.md +++ /dev/null @@ -1,81 +0,0 @@ -# How to enable Travis in a repository under the Node.js GitHub organization - -Since we don't allow third-party access to the Node.js GitHub organization -except our own bots, when a repository is transferred into the Node.js -foundation, Travis won't be able to update the build status of pull requests -automatically. Instead, we need to use our own GitHub bot to pull the status -from Travis and send the update in GitHub. This is what needs to be done: - -### Step 1: Travis setup - -Make sure Travis can listen to the push and pull request events of the -repository. Go to "Settings -> Integrations & services" page of the -repository. If Travis has been integrated with the repository before, -then it should be listed under "Services". If not, click on the dropdown -"Add service", and search for Travis to add it. - -The service does not really have to be configured to enable Travis. All of the -following configurations work: - -* User and Token configured as someone who is not "nodejs", and Domain is - blank -* User and Token left blank, Domain is `notify.travis-ci.org` -* User and Token configured as someone who is not "nodejs", Domain is - `notify.travis-ci.org` -* User, Token, Domain all left blank - -If `https://travis-ci.org/nodejs/{reponame}` starts building new pull requests -or pull request updates in the repository after the service is enabled, then -the Travis end is set up. - -### Step 2: add the bot to your team - -Go to the "Settings -> Collaborators & teams" page of the repository, add -`@nodejs-github-bot`, or the `@nodejs/bots` team to the collaborators of the -repository, so that the GitHub bot account has write access to it. If there -are 404 responses in the logs of build status updates sent from the bot, it -usually means the bot is not granted write access to the repository. - -### Step3: add the webhook for the bot - -On the "Settings -> Webhooks" page, add a new webhook for the bot: - -* Payload URL: `http://github-bot.nodejs.org:3333/hooks/github` -* Content type: `application/json` -* Secret: can be obtained in the https://github.com/nodejs/secrets repository, - or ask someone from the build working group to add the webhook for you. -* In "Which events would you like to trigger this webhook?", select "Let me - select individual events.", check "Push" and "Pull Request". -* Finally, check "Active" and save the webhook. GitHub will send a test - payload to the bot, if it comes back green, the bot is set up with the - repository. - -### Step 4: update the bot - -Open a pull request to https://github.com/nodejs/github-bot, adding the -repository to the `enabledRepos` in -https://github.com/nodejs/github-bot/blob/master/scripts/display-travis-status.js, -so the bot will not ignore the events from your repository and start sending -updates. - -### How it works - -The bot works like this: - -1. When a pull request is opened or updated, GitHub will send an event to both - Travis (configured in step 1) and the bot (step 3). -2. Travis will start the build, and the bot will start polling Travis - for build status (this requires step 4 otherwise the bot would ignore the - event). -3. When the bot finds the build matching the last commit in the PR, it - will update the build status of that PR as "pending" (this update requires - step 2). -4. When a poll comes back as a successful build, the bot will update the - build status as "success". - -### Aside - -If the transferred project is used across different platforms, consider -transferring the testing to the Node.js build infrastructure as well, so that -it can be tested across the platforms supported by Node.js. Open an issue in -https://github.com/nodejs/build for help getting the transfer done. diff --git a/transfer-repo-into-the-org.md b/transfer-repo-into-the-org.md index 2850c648..34e02a7e 100644 --- a/transfer-repo-into-the-org.md +++ b/transfer-repo-into-the-org.md @@ -54,22 +54,8 @@ The releases should still by done by the original releasers. See [NPM Management](./npm-management.md) on more about the Node.js foundation npm account. -## Step 5. Fix integrations and Webhooks - -If the repository has previously configured external integrations and webhooks -(for example, the Travis CI), do know that we do not allow third-party -applications integrated into the organization. It's fine to keep the -per-repository webhooks or add new ones, but a lot of external services require -permissions to read the list of repositories of the organization in addition -to webhooks, so the previous integrations may stop working once the repository -is transferred. - -It is possible to bring Travis integration back using the Node.js GitHub bot. -See the guide on [enabling Travis in a repository under the Node.js GitHub organization][]. - [coc]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md [GitHub's documentation on transferring repos]: https://help.github.com/articles/about-repository-transfers/ [Node.js GitHub Organization Management Policy]: https://github.com/nodejs/TSC/blob/master/GitHub-Org-Management-Policy.md#repositories [the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md [the issue tracker of the Node.js admin repository]: https://github.com/nodejs/admin/issues -[enabling Travis in a repository under the Node.js GitHub organization]: ./enable-travis-under-nodejs.md \ No newline at end of file From bf7c9ab84552a66aa57ac1f62c86a69d56aa4635 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Sat, 15 Dec 2018 06:52:14 +0800 Subject: [PATCH 5/6] Apply suggestions from code review Co-Authored-By: joyeecheung --- npm-management.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/npm-management.md b/npm-management.md index d813735c..8ef14cd1 100644 --- a/npm-management.md +++ b/npm-management.md @@ -7,6 +7,7 @@ We have a number of modules under the Node.js Foundation including: * [node-gyp](https://github.com/nodejs/node-gyp) * [node-inspect](https://github.com/nodejs/node-inspect) * [node-report](https://github.com/nodejs/node-report) +* [readable-stream](https://github.com/nodejs/readable-stream) We need to make sure that we have continuity in terms of being able to publish and update these modules. @@ -15,7 +16,7 @@ We have decided to manage these modules as follows: * Create a user called [`nodejs-foundation`][] who we always add as one of the collaborators with admin rights and for which the password is maintained by - the build workgroup. + the Build Working Group. * We would then add individuals as collaborators who can also publish. Generally, a module push will be done by the additional collaborators. The `nodejs-foundation` user is intended to be used as a backup as opposed @@ -38,4 +39,4 @@ encrypted form in the [secrets repo][]. [`nodejs-foundation`]: https://www.npmjs.com/~nodejs-foundation -[secrets repo]: https://github.com/nodejs/secrets/tree/master/test/test_credentials.md +https://github.com/nodejs-private/secrets/blob/master/build/test/test_logins.md From 61e9f33ea52e455a56c2d751ce48e28ff660b21d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20Zasso?= Date: Wed, 19 Dec 2018 07:36:34 +0800 Subject: [PATCH 6/6] Update npm-management.md Co-Authored-By: joyeecheung --- npm-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/npm-management.md b/npm-management.md index 8ef14cd1..a0667a22 100644 --- a/npm-management.md +++ b/npm-management.md @@ -39,4 +39,4 @@ encrypted form in the [secrets repo][]. [`nodejs-foundation`]: https://www.npmjs.com/~nodejs-foundation -https://github.com/nodejs-private/secrets/blob/master/build/test/test_logins.md +[secrets repo]: https://github.com/nodejs-private/secrets/blob/master/build/test/test_logins.md