From a6892c461d0362d98d35d00d5c8c7a77a0a8a59c Mon Sep 17 00:00:00 2001 From: Jasper van Merle Date: Wed, 21 Aug 2019 17:21:00 +0200 Subject: [PATCH] Update guidelines regarding updating existing documentations --- .../CODE_OF_CONDUCT.md | 0 .github/CONTRIBUTING.md | 15 ++++++++-- .github/PULL_REQUEST_TEMPLATE.md | 29 +++++++++++++++++++ PULL_REQUEST_TEMPLATE.md | 11 ------- docs/maintainers.md | 5 +--- 5 files changed, 43 insertions(+), 17 deletions(-) rename CODE_OF_CONDUCT.md => .github/CODE_OF_CONDUCT.md (100%) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 PULL_REQUEST_TEMPLATE.md diff --git a/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to .github/CODE_OF_CONDUCT.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0c53b8e9..8604af74 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -58,9 +58,20 @@ In addition to the [guidelines for contributing code](#contributing-code-and-fea ## Updating existing documentations -Please don't submit a pull request updating only the version number and/or the attribution of a documentation. Do submit a pull request if a bigger change is required in the scraper and you've verified that it works. +If the latest [documentation versions report](https://github.com/freeCodeCamp/devdocs/issues?utf8=%E2%9C%93&q=Documentation+versions+report+is%3Aissue+author%3Adevdocs-bot+sort%3Acreated-desc) wrongly shows a documentation to be up-to-date, please open an issue or a PR to fix it. -To ask that an existing documentation be updated, first check the latest [documentation versions report](https://github.com/freeCodeCamp/devdocs/issues?utf8=%E2%9C%93&q=Documentation+versions+report+is%3Aissue+author%3Adevdocs-bot+sort%3Acreated-desc). Only create an issue if the documentation has been wrongly marked as up-to-date. +**Important:** PR's that update documentation versions that do not contain the checklist shown to you in section B of the PR template may be closed without review. + +Follow the following steps to update documentations to their latest version: + +1. Make version/release changes in the scraper file. +2. Check if the license is still correct. If you update `options[:attribution]`, also update the documentation's entry in the array in [`assets/javascripts/templates/pages/about_tmpl.coffee`](../assets/javascripts/templates/pages/about_tmpl.coffee) to match. +3. If the documentation has a custom icon, ensure the icons in public/icons/*your_scraper_name*/ are up-to-date. If you pull the updated icon from a place different than the one specified in the `SOURCE` file, make sure to replace the old link with the new one. +4. If `self.links` is defined, check if the home and code urls are still correct. +5. Generate the docs using `thor docs:generate `. +6. Make sure `thor docs:generate` doesn't show errors and that the documentation still works well. The `thor docs:generate` command outputs a summary of the changes, which helps identifying issues (e.g. deleted files) and new pages to check out in the app. Verify locally that everything works, especially the files that were created (if any), and that the categorization of entries is still good. Often, updates will require code changes in the scraper or it's filters to tweak some new markup in the source website or to categorize new entries. +7. Repeat steps 5 and 6 for all versions that you updated. `thor docs:generate` accepts a `--version` argument to specify which version to scrape. +8. Create a PR and make sure to fill the checklist in section B of the PR template (remove the other sections). ## Coding conventions diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..e37a76f8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,29 @@ + + + + + + + + +If you’re adding a new scraper, please ensure that you have: + +- [ ] Tested the scraper on a local copy of DevDocs +- [ ] Ensured that the docs are styled similarly to other docs on DevDocs + +- [ ] Added these files to the public/icons/*your_scraper_name*/ directory: + - [ ] `16.png`: a 16×16 pixel icon for the doc + - [ ] `16@2x.png`: a 32×32 pixel icon for the doc + - [ ] `SOURCE`: A text file containing the URL to the page the image can be found on or the URL of the original image itself + + + + +If you're updating an existing documentation to it's latest version, please ensure that you have: + +- [ ] Updated the versions and releases in the scraper file +- [ ] Ensured the license is up-to-date and that the documentation's entry in the array in `about_tmpl.coffee` matches it's data in `self.attribution` +- [ ] Ensured the icons and the `SOURCE` file in public/icons/*your_scraper_name*/ are up-to-date if the documentation has a custom icon +- [ ] Ensured `self.links` contains up-to-date urls if `self.links` is defined +- [ ] Tested the changes locally to ensure the scraper still works without errors +- [ ] Tested the changes locally to ensure the scraped documentation still looks consistent with the rest of DevDocs and that the categorization of entries is still good diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index 0df55970..00000000 --- a/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,11 +0,0 @@ -If you’re adding a new scraper, please ensure that you have: - -- [ ] Tested the scraper on a local copy of DevDocs -- [ ] Ensured that the docs are styled similarly to other docs on DevDocs - -- [ ] Added these files to the public/icons/*your_scraper_name*/ directory: - - [ ] `16.png`: a 16×16 pixel icon for the doc - - [ ] `16@2x.png`: a 32×32 pixel icon for the doc - - [ ] `SOURCE`: A text file containing the URL to the page the image can be found on or the URL of the original image itself - - diff --git a/docs/maintainers.md b/docs/maintainers.md index da7e910e..5af76097 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -14,10 +14,7 @@ This document is intended for [DevDocs maintainers](#list-of-maintainers). The process for updating docs is as follow: -- Make version/release changes in the scraper file. -- If needed, update the copyright notice of the documentation in the scraper file (`options[:attribution]`) and the about page (`about_tmpl.coffee`). The copyright notice must be the same as the one on the original documentation. -- Run `thor docs:generate`. -- Make sure the documentation still works well. The `thor docs:generate` command outputs a summary of the changes, which helps identifying issues (e.g. deleted files) and new pages to check out in the app. Verify locally that everything works, especially the files that were created (if any), and that the categorization of entries is still good. Often, updates will require code changes to tweak some new markup in the source website or categorize new entries. +- Follow the checklist in [CONTRIBUTING.md#updating-existing-documentations](../.github/CONTRIBUTING.md#updating-existing-documentations). - Commit the changes (protip: use the `thor docs:commit` command documented below). - Optional: do more updates. - Run `thor docs:upload` (documented below).