Skip to content

Commit

Permalink
Removing step 7 (squashing) and formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
Zlatko Knezevic committed Jun 30, 2015
1 parent c3c8872 commit f3786b9
Showing 1 changed file with 42 additions and 21 deletions.
63 changes: 42 additions & 21 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,58 @@
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:

pip install sphinx

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

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 ###

Expand All @@ -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 ##

Expand All @@ -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

0 comments on commit f3786b9

Please sign in to comment.