@ -58,9 +58,20 @@ In addition to the [guidelines for contributing code](#contributing-code-and-fea
## Updating existing documentations
## 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 <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.
4. If `self.links` is defined, check if the home and code urls are still correct.
5. Generate the docs using `thor docs:generate <doc>`.
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).
<!-- Remove the sections that don't apply to your PR. -->
<!-- Replace the `[ ]` with a `[x]` in checklists once you’ve completed each step. -->
<!-- Please create a draft PR when you haven't completed all steps yet upon creation of the PR. -->
<!-- SECTION A - Adding a new scraper -->
<!-- See https://github.com/freeCodeCamp/devdocs/blob/master/.github/CONTRIBUTING.md#contributing-new-documentations -->
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
<!-- If the docs don’t have an icon, delete the next four items: -->
- [ ] Added these files to the <code>public/icons/*your_scraper_name*/</code> 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
<!-- SECTION B - Updating an existing documentation to it's latest version -->
<!-- See https://github.com/freeCodeCamp/devdocs/blob/master/.github/CONTRIBUTING.md#updating-existing-documentations -->
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 <code>public/icons/*your_scraper_name*/</code> 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
@ -14,10 +14,7 @@ This document is intended for [DevDocs maintainers](#list-of-maintainers).
The process for updating docs is as follow:
The process for updating docs is as follow:
- Make version/release changes in the scraper file.
- Follow the checklist in [CONTRIBUTING.md#updating-existing-documentations](../.github/CONTRIBUTING.md#updating-existing-documentations).
- 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.
- Commit the changes (protip: use the `thor docs:commit` command documented below).
- Commit the changes (protip: use the `thor docs:commit` command documented below).
Jasper van Merle
6 years ago