@ -27,8 +27,6 @@ Want to contribute? Great. Please review the following guidelines carefully and
2. Make sure your feature fits DevDocs's [vision](https://github.com/freeCodeCamp/devdocs/blob/master/README.md#vision).
3. Provide a clear and detailed explanation of the feature and why it's important to add it.
For general feedback and ideas, please use the [mailing list](https://groups.google.com/d/forum/devdocs).
## Requesting new documentations
Please don't open issues to request new documentations.
@ -37,7 +35,7 @@ Use the [Trello board](https://trello.com/b/6BmTulfx/devdocs-documentation) wher
## Contributing code and features
1. Search for existing issues; someone may already be working on a similar feature.
2. Before embarking on any significant pull request, please open an issue describing the changes you intend to make. Otherwise you risk spending a lot of time working on something I may not want to merge. This also tells other contributors that you're working on the feature.
2. Before embarking on any significant pull request, please open an issue describing the changes you intend to make. Otherwise you risk spending a lot of time working on something we may not want to merge. This also tells other contributors that you're working on the feature.
3. Follow the [coding conventions](#coding-conventions).
4. If you're modifying the Ruby code, include tests and ensure they pass.
5. Try to keep your pull request small and simple.
@ -65,13 +63,6 @@ Please don't submit a pull request updating the version number of a documentatio
To ask that an existing documentation be updated, please use the [Trello board](https://trello.com/c/2B0hmW7M/52-request-updates-here).
## Other contributions
Besides new docs and features, here are other ways you can contribute:
* **Improve our copy.** English isn't my first language so if you notice grammatical or usage errors, feel free to submit a pull request — it'll be much appreciated.
* **Participate in the issue tracker.** Your opinion matters — feel free to add comments to existing issues. You're also welcome to participate to the [mailing list](https://groups.google.com/d/forum/devdocs).
## Coding conventions
* two spaces; no tabs
@ -80,4 +71,4 @@ Besides new docs and features, here are other ways you can contribute:
## Questions?
If you have any questions, please feel free to ask on the [mailing list](https://groups.google.com/d/forum/devdocs).
If you have any questions, please feel free to ask them on the contributor chat room on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs).
# [DevDocs](https://devdocs.io) — API Documentation Browser [](https://travis-ci.org/freeCodeCamp/devdocs)
DevDocs combines multiple API documentations in a fast, organized, and searchable interface.
DevDocs combines multiple developer documentations in a clean and organized web UI with instant search, offline support, mobile version, dark theme, keyboard shortcuts, and more.
* Created by [Thibaut Courouble](https://thibaut.me)
DevDocs was created by [Thibaut Courouble](https://thibaut.me) and is operated by [freeCodeCamp](https://www.freecodecamp.org).
Keep track of development news:
* Join the contributor chat room on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs)
* Watch the repository on [GitHub](https://github.com/freeCodeCamp/devdocs/subscription)
* Follow [@DevDocs](https://twitter.com/DevDocs) on Twitter
* Join the [mailing list](https://groups.google.com/d/forum/devdocs)
Unless you wish to contribute to the project, I recommend using the hosted version at [devdocs.io](https://devdocs.io). It's up-to-date and works offline out-of-the-box.
Unless you wish to contribute to the project, we recommend using the hosted version at [devdocs.io](https://devdocs.io). It's up-to-date and works offline out-of-the-box.
DevDocs is made of two pieces: a Ruby scraper that generates the documentation and metadata, and a JavaScript app powered by a small Sinatra app.
DevDocs requires Ruby 2.5.1, libcurl, and a JavaScript runtime supported by [ExecJS](https://github.com/rails/execjs#readme) (included in OS X and Windows; [Node.js](https://nodejs.org/en/) on Linux). Once you have these installed, run the following commands:
DevDocs requires Ruby 2.6.0, libcurl, and a JavaScript runtime supported by [ExecJS](https://github.com/rails/execjs#readme) (included in OS X and Windows; [Node.js](https://nodejs.org/en/) on Linux). Once you have these installed, run the following commands:
```
git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs
@ -129,20 +128,20 @@ If multiple versions of Ruby are installed on your system, commands must be run
## Contributing
Contributions are welcome. Please read the [contributing guidelines](https://github.com/freeCodeCamp/devdocs/blob/master/CONTRIBUTING.md).
Contributions are welcome. Please read the [contributing guidelines](https://github.com/freeCodeCamp/devdocs/blob/master/.github/CONTRIBUTING.md).
DevDocs's own documentation is available on the [wiki](https://github.com/freeCodeCamp/devdocs/wiki).
## Copyright / License
Copyright 2013-2018 Thibaut Courouble and [other contributors](https://github.com/freeCodeCamp/devdocs/graphs/contributors)
Copyright 2013-2019 Thibaut Courouble and [other contributors](https://github.com/freeCodeCamp/devdocs/graphs/contributors)
This software is licensed under the terms of the Mozilla Public License v2.0. See the [COPYRIGHT](https://github.com/freeCodeCamp/devdocs/blob/master/COPYRIGHT) and [LICENSE](https://github.com/freeCodeCamp/devdocs/blob/master/LICENSE) files.
Please do not use the name DevDocs to endorse or promote products derived from this software without my permission, except as may be necessary to comply with the notice/attribution requirements.
Please do not use the name DevDocs to endorse or promote products derived from this software without the maintainers' permission, except as may be necessary to comply with the notice/attribution requirements.
I also wish that any documentation file generated using this software be attributed to DevDocs. Let's be fair to all contributors by giving credit where credit's due. Thanks!
We also wish that any documentation file generated using this software be attributed to DevDocs. Let's be fair to all contributors by giving credit where credit's due. Thanks!
## Questions?
If you have any questions, please feel free to ask them on the [mailing list](https://groups.google.com/d/forum/devdocs).
If you have any questions, please feel free to ask them on the contributor chat room on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs).
<p>DevDocsisfreeand<ahref="https://github.com/freeCodeCamp/devdocs">opensource</a>. It was created by <a href="https://thibaut.me">Thibaut Courouble</a> and is operated by <a href="https://www.freecodecamp.org/">freeCodeCamp</a>.
<li>Run <code>thor docs:download --installed</code> to update all downloaded documentations.
<li>To be notified about new versions, don't forget to <a href="https://github.com/freeCodeCamp/devdocs/subscription">watch the repository</a> on GitHub.
<li>The <a href="https://github.com/freeCodeCamp/devdocs/issues">issue tracker</a> is the preferred channel for bug reports and
feature requests. For everything else, use the <a href="https://groups.google.com/d/forum/devdocs">mailing list</a>.
feature requests. For everything else, use <a href="https://gitter.im/FreeCodeCamp/DevDocs">Gitter</a>.
<li>Contributions are welcome. See the <a href="https://github.com/freeCodeCamp/devdocs/blob/master/CONTRIBUTING.md">guidelines</a>.
<li>DevDocs is licensed under the terms of the Mozilla Public License v2.0. For more information,
see the <a href="https://github.com/freeCodeCamp/devdocs/blob/master/COPYRIGHT">COPYRIGHT</a> and
This document is intended for [DevDocs maintainers](#list-of-maintainers).
## Merging pull requests
- Unless the change is trivial or in an area that you are familiar with, PRs should be approved by at least two maintainers before being merged.
- PRs that add or update documentations should always be merged locally, and the app deployed, before the merge is pushed to GitHub.
This workflow is required because there is a dependency between the local and production environments. The `thor docs:download` command downloads documentations from production files uploaded by the `thor docs:upload` command. If a PR adding a new documentation is merged and pushed to GitHub before the files have been uploaded to production, the `thor docs:download` will fail for the new documentation and the docker container will not build properly until the new documentation is deployed to production.
## Updating docs
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.
- Commit the changes (protip: use the `thor docs:commit` command documented below).
- Optional: do more updates.
- Run `thor docs:upload` (documented below).
- [Deploy the app](#deploying-devdocs) and verify that everything works in production.
- Push to GitHub.
- Run `thor docs:clean` (documented below).
Note: changes to `public/docs/docs.json` should never be committed. This file reflects which documentations have been downloaded or generated locally, which is always none on a fresh `git clone`.
## Setup requirements
In order to deploy DevDocs, you must:
- be given access to Heroku, [configure the Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) on your computer, and familiarize yourself with Heroku's UI and CLI, as well as that of New Relic (accessible through [the Heroku dashboard](https://dashboard.heroku.com/apps/devdocs)).
- be given access to DevDocs's [Sentry instance](https://sentry.io/devdocs/devdocs-js/) (for JS error tracking) and familiarize yourself with its UI.
- be provided with DevDocs's S3 credentials, and install (`brew install awscli` on macOS) and [configure](https://docs.aws.amazon.com/cli/latest/reference/configure/) the AWS CLI on your computer. The configuration must add a named profile called "devdocs":
```
aws configure --profile devdocs
```
- be provided with DevDocs's MaxCDN push zone credentials, and add them to your `.bash_profile` as such:
```
export DEVDOCS_DL_USERNAME="username"
export DEVDOCS_DL_PASSWORD="password"
```
## Thor commands
In addition to the [publicly-documented commands](https://github.com/freeCodeCamp/devdocs#available-commands), the following commands are aimed at DevDocs maintainers:
- `thor docs:package`
Generates packages for one or more documentations. Those packages are intended to be uploaded to DevDocs's MaxCDN push zone by maintainers via the `thor docs:upload` command, and downloaded by users via the `thor docs:download` command.
Versions can be specified as such: `thor docs:package rails@5.2 node@10\ LTS`.
Packages can also be automatically generated during the scraping process by passing the `--package` option to `thor docs:generate`.
- `thor docs:upload`
This command does two operations:
1. sync the files for the specified documentations with S3 (used by the Heroku app);
2. upload the documentations' packages to DevDocs's MaxCDN push zone (used by the `thor docs:download` command).
For the command to work, you must have the AWS CLI and MaxCDN credentials configured as indicated above.
**Important:** the app should always be deployed immediately after this command has finished running. Do not run this command unless you are able and ready to deploy DevDocs.
To upload all documentations that are packaged on your computer, run `thor docs:upload --packaged`.
To test your configuration and the effect of this command without uploading anything, pass the `--dryrun` option.
- `thor docs:commit`
Shortcut command to create a Git commit for a given documentation once it has been updated. Scraper and `assets/` file changes will be committed. The commit message will include the most recent version that the documentation was updated to. If some files were missed by the commit, use `git commit --amend` to add them to the commit. The command may be run before `thor docs:upload` is run, but the commit should not be pushed to GitHub before the files have been uploaded and the app deployed.
- `thor docs:clean`
Shortcut command to delete all package files (once uploaded via `thor docs:upload`, they are not needed anymore).
## Deploying DevDocs
Once docs have been uploaded via `thor docs:upload` (if applicable), deploying DevDocs is as simple as running `git push heroku master`. See [Heroku's documentation](https://devcenter.heroku.com/articles/git) for more information.
- If you're deploying documentation updates, verify that the documentations work properly once the deploy is done (you will need to reload [devdocs.io](https://devdocs.io/) a couple times for the application cache to update and the new version to load).
- If you're deploying frontend changes, monitor [Sentry](https://sentry.io/devdocs/devdocs-js/) for new JS errors once the deploy is done.
- If you're deploying server changes, monitor New Relic (accessible through [the Heroku dashboard](https://dashboard.heroku.com/apps/devdocs)) for Ruby exceptions and throughput or response time changes once the deploy is done.
If any issue arises, run `heroku rollback` to rollback to the previous of the app (this can also be done via Heroku's UI). Note that this will not revert changes made to documentation files that were uploaded via `thor docs:upload`. Try and fix the issue as quickly as possible, then re-deploy the app. Reach out to other maintainers if you need help.
If this is your first deploy, make sure another maintainer is around to assist.
## List of maintainers
- [Beau Carnes](https://github.com/beaucarnes)
- [Jed Fox](https://github.com/j-f1)
- [Jasper van Merle](https://github.com/jmerle)
- [Thibaut Courouble](https://github.com/thibaut)
Interested in helping maintain DevDocs? Come talk to us on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs) :)
Jasper van Merle
6 years ago
committed by