Update guidelines on updating existing documentations
Unified · Split
File renamed without changes.
| @@ -58,9 +58,20 @@ In addition to the [guidelines for contributing code](#contributing-code-and-fea · 57 unmodified lines | ||
| 58 | 58 | |
| 59 | 59 | ## Updating existing documentations |
| 60 | 60 | |
| 61 | −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. | |
| 61 | +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. | |
| 62 | 62 | |
| 63 | −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. | |
| 63 | +**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. | |
| 64 | + | |
| 65 | +Follow the following steps to update documentations to their latest version: | |
| 66 | + | |
| 67 | +1. Make version/release changes in the scraper file. | |
| 68 | +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. | |
| 69 | +3. If the documentation has a custom icon, ensure the icons in <code>public/icons/*your_scraper_name*/</code> 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. | |
| 70 | +4. If `self.links` is defined, check if the urls are still correct. | |
| 71 | +5. Generate the docs using `thor docs:generate <doc>`. | |
| 72 | +6. Make sure `thor docs:generate` doesn't show errors and that the documentation still works well. Verify locally that everything works and that the categorization of entries is still good. Often, updates will require code changes in the scraper or its filters to tweak some new markup in the source website or to categorize new entries. | |
| 73 | +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. | |
| 74 | +8. Create a PR and make sure to fill the checklist in section B of the PR template (remove the other sections). | |
| 64 | 75 | |
| 65 | 76 | ## Coding conventions |
| 66 | 77 | |
| @@ -0,0 +1,31 @@ | ||
| 1 | +<!-- Remove the sections that don't apply to your PR. --> | |
| 2 | + | |
| 3 | +<!-- Replace the `[ ]` with a `[x]` in checklists once you’ve completed each step. --> | |
| 4 | +<!-- Please create a draft PR when you haven't completed all steps yet upon creation of the PR. --> | |
| 5 | + | |
| 6 | +<!-- SECTION A - Adding a new scraper --> | |
| 7 | +<!-- See https://github.com/freeCodeCamp/devdocs/blob/master/.github/CONTRIBUTING.md#contributing-new-documentations --> | |
| 8 | + | |
| 9 | +If you’re adding a new scraper, please ensure that you have: | |
| 10 | + | |
| 11 | +- [ ] Tested the scraper on a local copy of DevDocs | |
| 12 | +- [ ] Ensured that the docs are styled similarly to other docs on DevDocs | |
| 13 | +<!-- If the docs don’t have an icon, delete the next four items: --> | |
| 14 | +- [ ] Added these files to the <code>public/icons/*your_scraper_name*/</code> directory: | |
| 15 | + - [ ] `16.png`: a 16×16 pixel icon for the doc | |
| 16 | + - [ ] `16@2x.png`: a 32×32 pixel icon for the doc | |
| 17 | + - [ ] `SOURCE`: A text file containing the URL to the page the image can be found on or the URL of the original image itself | |
| 18 | + | |
| 19 | +<!-- SECTION B - Updating an existing documentation to it's latest version --> | |
| 20 | +<!-- See https://github.com/freeCodeCamp/devdocs/blob/master/.github/CONTRIBUTING.md#updating-existing-documentations --> | |
| 21 | + | |
| 22 | +If you're updating an existing documentation to it's latest version, please ensure that you have: | |
| 23 | + | |
| 24 | +- [ ] Updated the versions and releases in the scraper file | |
| 25 | +- [ ] 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` | |
| 26 | +- [ ] Ensured the icons and the `SOURCE` file in <code>public/icons/*your_scraper_name*/</code> are up-to-date if the documentation has a custom icon | |
| 27 | +- [ ] Ensured `self.links` contains up-to-date urls if `self.links` is defined | |
| 28 | +- [ ] Tested the changes locally to ensure: | |
| 29 | + - The scraper still works without errors | |
| 30 | + - The scraped documentation still looks consistent with the rest of DevDocs | |
| 31 | + - The categorization of entries is still good | |
| @@ -1,11 +0,0 @@ | ||
| 1 | −If you’re adding a new scraper, please ensure that you have: | |
| 2 | − | |
| 3 | −- [ ] Tested the scraper on a local copy of DevDocs | |
| 4 | −- [ ] Ensured that the docs are styled similarly to other docs on DevDocs | |
| 5 | −<!-- If the docs don’t have an icon, delete the next four items: --> | |
| 6 | −- [ ] Added these files to the <code>public/icons/*your_scraper_name*/</code> directory: | |
| 7 | − - [ ] `16.png`: a 16×16 pixel icon for the doc | |
| 8 | − - [ ] `16@2x.png`: a 32×32 pixel icon for the doc | |
| 9 | − - [ ] `SOURCE`: A text file containing the URL to the page the image can be found on or the URL of the original image itself | |
| 10 | − | |
| 11 | −<!-- Replace the `[ ]` with a `[x]` once you’ve completed each step. --> | |
| @@ -14,10 +14,7 @@ This document is intended for [DevDocs maintainers](#list-of-maintainers). · 13 unmodified lines | ||
| 14 | 14 | |
| 15 | 15 | The process for updating docs is as follow: |
| 16 | 16 | |
| 17 | −- Make version/release changes in the scraper file. | |
| 18 | −- 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. | |
| 19 | −- Run `thor docs:generate`. | |
| 20 | −- 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. | |
| 17 | +- Follow the checklist in [CONTRIBUTING.md#updating-existing-documentations](../.github/CONTRIBUTING.md#updating-existing-documentations). | |
| 21 | 18 | - Commit the changes (protip: use the `thor docs:commit` command documented below). |
| 22 | 19 | - Optional: do more updates. |
| 23 | 20 | - Run `thor docs:upload` (documented below). |