diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f32fc68a0aee5..8df1f5724e9a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,17 @@ Contributing ====== -The documentation is built using [Sphinx](http://sphinx-doc.org) and [reStructuredText](http://sphinx-doc.org/rest.html), and then hosted by [ReadTheDocs](http://dotnet.readthedocs.org). +The documentation is built using [Sphinx](http://sphinx-doc.org) and +[reStructuredText](http://sphinx-doc.org/rest.html), and then hosted by +[ReadTheDocs](http://dotnet.readthedocs.org). ## Building the Docs -To build the docs, you will need to install [python](https://www.python.org/downloads/) (version 2 or higher). If you are running Windows, you will want to add the Python install folder and the \Scripts\ folder to your `PATH` environment variable (C:\Python34;C:\Python34\Scripts). +To build the docs, you will need to install +[python](https://www.python.org/downloads/) (version 2 or higher). If you are +running Windows, you will want to add the Python install folder and the +\Scripts\ folder to your `PATH` environment variable +(C:\Python34;C:\Python34\Scripts). To install Sphinx, open a command prompt and run: @@ -13,11 +19,13 @@ To install Sphinx, open a command prompt and run: This may take a few minutes. -This project is also using a custom theme from ReadTheDocs, which you can install with: +This project is also using a custom theme from ReadTheDocs, which you can +install with: pip install sphinx_rtd_theme -Note that later if you wish to update your current, installed version of this theme, you should run: +Note that later if you wish to update your current, installed version of this +theme, you should run: pip install -U sphinx_rtd_theme @@ -25,17 +33,26 @@ You should now be able to navigate to the `docs` folder and run make html -which should generate the documentation in the _build folder. Open the _build/html/index.html file to view the generated documentation. +which should generate the documentation in the _build folder. Open the +_build/html/index.html file to view the generated documentation. If contributing new documentation content, please review: -- the [Sphinx Style Guide](http://documentation-style-guide-sphinx.readthedocs.org/en/latest/style-guide.html) +- the [Sphinx Style Guide](http://documentation-style-guide-sphinx.readthedocs. + org/en/latest/style-guide.html) ## Adding Content ## -Before adding content, submit an issue with a suggestion for your proposed article. Provide detail on what the article would discuss, and how it would relate to existing documentation. +Before adding content, submit an issue with a suggestion for your proposed +article. Provide detail on what the article would discuss, and how it would +relate to existing documentation. -Articles should be organized into logical groups or sections. Each section should be given a named folder (e.g. /yourfirst). That section contains the rst files for all articles in the section. For images and other static resources, create a subfolder that matches the name of the article. Within this subfolder, create a ``sample`` folder for code samples and a ``_static`` folder for images and other static content. +Articles should be organized into logical groups or sections. Each section +should be given a named folder (e.g. /yourfirst). That section contains the +rst files for all articles in the section. For images and other static +resources, create a subfolder that matches the name of the article. Within this +subfolder, create a ``sample`` folder for code samples and a ``_static`` folder + for images and other static content. ### Example Structure ### @@ -46,29 +63,31 @@ Articles should be organized into logical groups or sections. Each section shoul /_static portability_report.png ... -**Note:** Sphinx will automatically fix duplicate image names. There is no need to try to ensure uniqueness of static files beyond an individual article. +**Note:** Sphinx will automatically fix duplicate image names. There is no need +to try to ensure uniqueness of static files beyond an individual article. -Author information is kept in _authors.txt_ file in the docs folder. The authors should be specified by a name and a link to the author's GitHub profile. +Author information is kept in _authors.txt_ file in the docs folder. The authors + should be specified by a name and a link to the author's GitHub profile. ## Process for Contributing ## -**Step 1:** Open an Issue describing the article you wish to write and how it relates to existing content. Get approval to write your article. +**Step 1:** Open an Issue describing the article you wish to write and how it +relates to existing content. Get approval to write your article. **Step 2:** Fork the `/dotnet/core-docs` repo. **Step 3:** Create a `branch` for your article. -**Step 4:** Write your article, placing the article in its own folder and any needed images in a _static folder located in the same folder as the article. Be sure to follow the proper reStructuredText syntax. If you have code samples, place them in a folder within the `/samples/` folder. +**Step 4:** Write your article, placing the article in its own folder and any +needed images in a _static folder located in the same folder as the article. +Be sure to follow the proper reStructuredText syntax. If you have code samples, +place them in a folder within the `/samples/` folder. **Step 5:** Submit a Pull Request from your branch to `dotnet/core-docs/master`. -**Step 6:** Discuss the Pull Request with the .NET team; make any requested updates to your branch. When they are ready to accept the PR, they will add a "LGTM" (Looks Good To Me) comment. - -**Step 7:** The last step before your Pull Request is accepted is to [squash all commits](http://stackoverflow.com/questions/14534397/squash-all-my-commits-into-one-for-github-pull-request) into a single commit message. Do this in your branch, using the `rebase` git command. For example, if you want to squash the last 4 commits into a single commit, you would use: - - git rebase -i HEAD~4 - -The `-i` option stands for "interactive" and should open a text editor showing the last N commits, preceded with "pick ". Change all but the first instance of "pick " to "squash " and save the file and exit the editor. A more detailed answer is [available here](http://stackoverflow.com/a/6934882). +**Step 6:** Discuss the Pull Request with the .NET team; make any requested +updates to your branch. When they are ready to accept the PR, they will add a +"LGTM" (Looks Good To Me) comment and any other steps that are (maybe) needed. ## Common Pitfalls ## @@ -77,5 +96,7 @@ Below are some common pitfalls you should try to avoid: - Don't forget to submit an issue before starting work on an article - Don't forget to create a separate branch before working on your article - Don't update or `merge` your branch after you submit your pull request -- Don't forget to squash your commits once your pull request is ready to be accepted -- If updating code samples in `/samples/`, be sure any line number references in your article remain correct +- Don't forget to squash your commits once your pull request is ready to be + accepted +- If updating code samples in `/samples/`, be sure any line number references + in your article remain correct