forked from cloudfoundry/docs-cloudfoundry-concepts
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcontribute.html.md.erb
125 lines (79 loc) · 8.15 KB
/
contribute.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
---
title: Contributing Documentation
owner: Docs
---
## <a id='why'></a>Why Should You Contribute?
The Cloud Foundry documentation relies on contributions from the community to remain accurate, complete, and consumable.
Reasons to contribute to the Cloud Foundry documentation include:
* You have noticed that a topic is incorrect or incomplete.
* You are developing a new Cloud Foundry feature, and want to tell users know how to use it.
* You are a good person, and you want to help your fellow humans.
* You hate the idea of someone else having to go through what you just went through to figure something out. Such a waste; so inefficient.
## <a id='contribute'></a>How Can You Contribute?
The source files for all Cloud Foundry docs are hosted on [Github](http://github.com), and each docs page has a link to its Github source file at the bottom. The source files are in Markdown/HTML/embedded Ruby (`html.md.erb`) format.
If you use Github, the most direct and effective way to contribute to the docs is to [submit a pull request](#github-pr) or [raise an issue](#github-issue) in the Github repository containing the docs content that you want to change.
If you do not already use Github (or want to learn), you can contribute to the CF docs in [other ways](#non-github) that are also greatly appreciated.
Whichever way you contribute, please follow our [Advice for Contributors](#advice).
###<a id='pull-request'></a> Submit a Github Pull Request
If you have identified a problem with the docs and know the required content change, the fastest way to make the change is by submitting a pull request (PR).
The CF docs team typically accepts PRs within a day, but may need to ask follow-up questions.
Before your PRs can be accepted, you must have a [signed Contributor License Agreement](#sign-cla) (CLA) on file.
To submit a pull request, follow these steps:
1. **Prerequisite**: [Sign the CLA](#sign-cla) if you have not already done so.
1. Navigate to the topic that you want to modify.
1. To locate the GitHub source file that contains the content for the topic, scroll to the bottom of the page and click **Create a pull request or raise an issue on the source for this page in GitHub.**
1. Click the pencil icon in the upper right to edit the file in GitHub.
1. Make your desired changes.
1. Under **Commit changes** at the bottom of the page, enter a description of your change and click **Propose file change**.
1. Click **Create pull request**.
#### <a id='sign-cla'></a> Sign and Publicize the CLA
Before your Github pull request can be accepted, you must sign the Contributor License Agreement (CLA) as an individual or publicize your membership with an organization that has signed the CLA. To do this, perform the following steps:
1. Complete and sign the appropriate CLA, either [individual](https://www.cloudfoundry.org/wp-content/uploads/2017/01/CFF_Individual_CLA.pdf) or [corporate](https://www.cloudfoundry.org/wp-content/uploads/2017/01/CFF_Corporate_CLA.pdf).
1. Send a scan of the CLA to [email protected], as instructed in the CLA. When sending the individual CLA, provide your GitHub username. When sending the corporate CLA, provide a list of GitHub usernames that can make pull requests on behalf of your organization.
1. [Publicize](https://help.github.com/articles/publicizing-or-hiding-organization-membership/) your membership in the appropriate GitHub org.
If you do not have a CLA on file with the Cloud Foundry Foundation, the `cfdreddbot` notifies you after you submit the pull request.
If you receive the `cfdreddbot` notification, but are confident that you are already covered under a corporate or organizational CLA, then verify that you have [publicized](https://help.github.com/articles/publicizing-or-hiding-organization-membership/) your membership in an appropriate GitHub org.
###<a id='issue'></a> Raise a Github Issue
If you do not have specific edits to make, but want start a discussion or make a general suggestion, you can raise a Github issue.
Github issues generally take longer to resolve than pull requests. But if you describe the issue with helpful background information and specific and actionable instructions, the CF docs team can address it quickly.
Vague or partially-baked Github issues may remain unaddressed for some time.
To raise an issue on a GitHub repository:
1. Navigate to the topic that you want to modify.
1. To locate the GitHub source file that contains the content for the topic, scroll to the bottom of the page and click **Create a pull request or raise an issue on the source for this page in GitHub.**
1. Click the name of the repository where the topic is located. For example, `docs-deploying-cf`.
1. Click the **Issues** tab.
1. Click **New issue**.
1. Enter a title for your issue, and in the text box, describe the issue and provide links to the affected topic(s).
1. Click **Submit new issue**.
###<a id='non-github'></a> Contribute Without Github
To contribute to the CF docs without using Github, you can use the following:
* **Google Docs**: Write new docs content, or copy-paste existing content, into a [Google Drive](http://drive.google.com) document. Edit or comment on it, and share with the CF docs team at [email protected].
* **Email** the the CF docs team directly at [email protected].
* **Slack** the CF docs team through the [#cf-docs](https://cloudfoundry.slack.com/messages/C03B0T0D5/") channel in Cloud Foundry Slack.
## <a id='advice'></a> Advice for Contributors
The Cloud Foundry Documentation Team reviews and revises all contributions, so you can **focus on providing correct and complete information, and not worry about style and structure**.
Keep in mind:
* If your contribution is larger than a small correction, put yourselves in the shoes of a novice and read through it. Revise the text to answer any questions that might occur to a less experienced user.
* Who needs this information? Are they a developer or a platform operator?
* What are the specifics that a user needs to know in order to understand and perform the task? Instead of "the instance" or “the cluster,” explain the instance or cluster of what. Instead of "revise the code to..." explain where to revise the code.
* If you're giving instructions, include why you would want to do what you're describing. What's your specific situation, and what result do you seek?
For further guidance, contact the Cloud Foundry Documentation Team at [email protected] or through our `#cf-docs` channel on the [Cloud Foundry Slack](https://cloudfoundry.slack.com).
## <a id='preview'></a> How Can You Preview Your Documentation Changes?
The Cloud Foundry Documentation Team uses the tool [Bookbinder](https://github.com/pivotal-cf/bookbinder) to publish the Cloud Foundry documentation.
The instructions below explain how to use Bookbinder to preview your documentation changes locally. But you do not have to install or use Bookbinder in order to contribute to the Cloud Foundry documentation.
Perform the following steps to preview documentation changes with Bookbinder:
1. If you do not already have a workspace directory within your home directory, create one.
<pre class="terminal">$ mkdir ~/workspace</pre>
3. Identify the content repository where your documentation lives. For example, `https://github.com/cloudfoundry/docs-cloudfoundry-concepts`.
4. Clone the content repository. For example:
<pre class="terminal">$ git clone git<span>@</span>github.com:cloudfoundry/docs-cloudfoundry-concepts.git</pre>
5. Return to your workspace directory and clone the Cloud Foundry book.
<pre class="terminal">$ git clone git<span>@</span>github.com:cloudfoundry/docs-book-cloudfoundry.git</pre>
6. Change directory into the Cloud Foundry book.
<pre class="terminal">cd docs-book-cloudfoundry</a>
7. Run `bundle install` to install the necessary gems, including Bookbinder.
8. Use Bookbinder to create a live version of your docs:
<pre class="terminal">$ bundle exec bookbinder watch</pre>
9. Navigate to `http://localhost:4567` in a browser and navigate to the route where your docs are published. For instance, `http://localhost:4567/cf-cli/install-go-cli.html`.
<br><br>
Bookbinder automatically updates the live version of the docs whenever you make a change to the content repository.