Updating documentation for CircleCI 2.0 #491
Conversation
|
Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need the corporate CLA signed. If you have received this in error or have any questions, please contact us at [email protected]. Thanks! |
|
Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks! |
There was a problem hiding this comment.
Thanks @ashleytqy for writing this up. I have a few suggestions that I think will make things more clear. If you agree, do you mind making those changes?
docs/getting-started-publishing.md
Outdated
|
|
||
| If you're already using Circle CI for your project, all you need to do to enable automatic deployments is to configure Circle to run the `publish-gh-pages` script as part of the deployment step. | ||
|
|
||
| If not, here's how to setup Circle CI for your project: |
There was a problem hiding this comment.
I think we want people to run through these steps, even if they are already using CircleCI for their main open source project. I made a suggested change to the above text to make that clearer.
docs/getting-started-publishing.md
Outdated
| @@ -73,36 +73,42 @@ However, you can automate the publishing process with continuous integration (CI | |||
|
|
|||
| Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and yes, deploying changes to your website. All you need to do to automate deployment of your website is to invoke the `publish-gh-pages` script whenever your docs get updated. In the following section we'll be covering how to do just that using [Circle CI](https://circleci.com/), a popular continuous integration service provider. | |||
|
|
|||
| ### Using Circle CI | |||
| ### Using Circle CI 2.0 | |||
|
|
|||
| If you're already using Circle CI for your project, all you need to do to enable automatic deployments is to configure Circle to run the `publish-gh-pages` script as part of the deployment step. | |||
There was a problem hiding this comment.
Maybe we change this to:
"If you haven't done so already, you can setup CircleCI for your open source project. Afterwards, in order to enable automatic deployment of your site and documentation via CircleCI, just configure Circle to run the publish-gh-pages script as part of the deployment step. You can follow the steps below to get that setup."
docs/getting-started-publishing.md
Outdated
| 1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo. | ||
| 1. Create a new environment variable named "GITHUB_TOKEN", using your newly generated access token as the value. | ||
| 1. Open your `circle.yml` file and add the following under the `machine:` section to tell Circle to use relatively recent versions of node and npm, replacing npm with yarn if applicable: | ||
| 2. Log into GitHub as the `GIT_USER`. |
There was a problem hiding this comment.
I think you can keep the numbering for each line to 1. since markdown automatically increments the number depending on how many are in the list. That keeps us from having to manually renumber.
docs/getting-started-publishing.md
Outdated
| ```yml | ||
| version: 2 | ||
| jobs: | ||
| build: |
There was a problem hiding this comment.
Maybe build should be called deploy-website ?
docs/getting-started-publishing.md
Outdated
| version: 2 | ||
| build_and_deploy: | ||
| jobs: | ||
| - build |
There was a problem hiding this comment.
If you make that change above, this would be deploy-website too.
docs/getting-started-publishing.md
Outdated
| version: 2 | ||
| build_and_deploy: | ||
| jobs: | ||
| - build | ||
| ``` | ||
|
|
||
| Make sure to replace `<GIT_USER>` with the actual username of the GitHub account that will be used to publish the documentation. |
There was a problem hiding this comment.
Maybe this sentence should be:
"Make sure to replace all <....> in the command: sequence with appropriate values. For <GIT_USER>, it should be a GitHub account that has access to push documentation to your GitHub repo. Many times <GIT_USER> and <GITHUB_USERNAME> will be the same."
ashleytqy
force-pushed
the
ash.circleci2-docs
branch
from
e59a6b3 to
bf5e7fd
Compare
Motivation
To fix issue #483 – updating documentation to use CircleCI 2.0.
Changes made:
.circleci/config.yml. I find this useful as someone who isn't very familiar with CircleCI because the previous documentation wasn't very explicit as to how the whole file should look like, so it would be nice to be able to copy and paste a sample / default config file.Let me know if this looks right!
Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
N/A. No code changes, only documentation.
Related PRs
N/A