{"action":"created","comment":{"url":"https://api.github.com/repos/dotnet/core-docs/pulls/comments/68552011","id":68552011,"diff_hunk":"@@ -1,94 +1,107 @@\n Contributing\n ============\n \n-In this document: \n+Thank you for your interest in contributing to the .NET documentation!\n+\n+In this topic, you'll see the basic process for adding or updating content in our [documentation site](https://docs.microsoft.com/dotnet). For the detailed step-by-step process and instructions, please see the [official guide](https://github.com/Microsoft/Docs/blob/master/readme.md) in the [Microsoft/Docs](https://github.com/Microsoft/Docs) repo.\n+\n+In this topic, we'll cover: \n \n * [Adding content](#adding-content)\n * [Process for contributing](#process-for-contributing) \n * [Guidance checklist](#guidance-checklist)\n * [Building the docs](#building-the-docs)\n * [Contributing to samples](#contributing-to-samples)\n+* [Contributor License Agreement](#contributor-license-agreement)\n \n ## Adding content ##\n \n-Before adding content, please submit an issue describing your content proposal. For smaller changes or additions, feel free to make a pull request.\n+Before adding content, please submit an issue describing your content proposal. For smaller changes or additions, feel free to make a Pull Request (PR) without opening an issue.\n \n-Articles should be organized into logical groups or sections. Each section\n-should be given a named folder (e.g. /yourfirst). That section contains the\n-Markdown files for all articles in the section. For images and other static\n-resources, create a subfolder that matches the name of the article. Within this\n-subfolder, create a ``sample`` folder for code samples and a  ``_static`` folder\n- for images and other static content.\n+The content inside the **docs** folder is organized into sections that are reflected in our Table of Contents (TOC). \n+See where your article fits in the TOC and navigate to the folder associated to that section.\n+That folder contains the Markdown files for all articles in the section.\n+If necessary, create a new folder to place the files for your content.\n+For images and other static resources, create a subfolder called **media** inside the folder that contains your article, if it doesn't already exist.\n+Larger samples should be included in the samples folder under the root of the repo. \n \n ### Example structure ###\n \n     docs\n-      /concepts\n-      /getting-started\n-      /porting\n-        /_static\n-          portability_report.png\n-\t  ...\n-\n-Author information is kept in the Markdown file itself. Each author should have a link to an online presence for himself/herself. \n+      /about\n+      /core\n+        /porting\n+          /media\n+            portability_report.png\n+      ...\n+    samples\n+      /core\n+        /porting\n+          porting_sample.cs\n \n ## Process for contributing ##\n \n-**Step 1:** Open an Issue describing the article you wish to write and how it\n+**Step 1:** Open an issue describing the article you wish to write and how it\n relates to existing content. Get approval to write your article.\n \n **Step 2:** Fork the `/dotnet/core-docs` repo.\n \n **Step 3:** Create a `branch` for your article.\n \n-**Step 4:** Write your article, placing the article in its own folder and any\n-needed images in a _static folder located in the same folder as the article.\n-Be sure to follow the proper Markdown syntax. If you have code samples,\n-place them in a folder within the `/samples/` folder.  For writing guidelines, see\n-[our style guide](/styleguide.md). Also do not forget to remove the \"wrench\" icon \n-(🔧) from the TOC and the file heading, if applicable. \n+**Step 4:** Write your article. You can use [our template file](template.md) as your starting point. It contains our writing guidelines and also explains about the metadata required for each article, such as author information.\n+Also read our [voice and tone article](voice-tone.md).\n+Place the article in the appropriate folder and any needed images in a media folder located in the same folder as the article.\n+Be sure to follow the proper Markdown syntax. \n+If you have code samples, place them in a folder within the `/samples/` folder. \n+ Also do not forget to remove the \"wrench\" icon (🔧) from the TOC and the file heading, if applicable. \n \n-**Step 5:** Submit a Pull Request from your branch to `dotnet/core-docs/master`.\n+**Step 5:** Submit a PR from your branch to `dotnet/core-docs/master`.\n \n-**Step 6:** Discuss the Pull Request with the .NET team; make any requested\n-updates to your branch. When they are ready to accept the PR, they will add a\n-\"LGTM\" (Looks Good To Me) comment and any other steps that are (maybe) needed.\n+**Step 6:** Discuss the PR with the .NET team; make any requested updates to your branch. \n+When we are ready to accept the PR, we will add a \"LGTM\" (Looks Good To Me) comment and any other steps that are perhaps necessary.\n \n-## Guidance checklist ##\n+## DOs and DON'Ts ##\n \n-Below is a short list of guiding rules that you should keep in mind when you are\n-contributing to .NET Core documentation.\n+Below is a short list of guiding rules that you should keep in mind when you are contributing to .NET documentation.\n \n-- Don't forget to submit an issue before starting work on an article\n-- Don't forget to create a separate branch before working on your article\n-- Don't update or `merge` your branch after you submit your pull request\n-- If updating code samples in `/samples/`, be sure any line number references\n-\tin your article remain correct\n+- **DON'T** surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time.\n+- **DO** read our [voice and tone](voice-tone.md) guidelines.\n+- **DO** use our [template](template.md) file as the starting point of your work. \n+- **DO** create a separate branch before working on your article. \n+- **DO** blog and tweet (or whatever) about your contributions, frequently!\n+- **DON'T** update or `merge` your branch after you submit your PR.\n \n ## Building the docs ##\n \n-The documentation is built using [docfx](http://dotnet.github.io/docfx/) and\n-[Markdown](https://daringfireball.net/projects/markdown/syntax). It is hosted on the [.NET Core](http://dotnet.github.io/) website. \n+The documentation is built using Open Publishing, [DocFX](http://dotnet.github.io/docfx/) and\n+[Markdown](https://daringfireball.net/projects/markdown/syntax). It is hosted at [https://docs.microsoft.com/dotnet](https://docs.microsoft.com/dotnet). \n \n-To build the docs, you will need to install\n-[docfx](http://dotnet.github.io/docfx/); latest versions are the best. \n+To build the docs locally, you will need to install [DocFX](https://dotnet.github.io/docfx/); latest versions are the best.\n \n-There are several ways to use docfx, and most of them are covered in the docfx [getting started guide](http://aspnet.github.io/docfx/tutorial/docfx_getting_started.html). This small guide will use the [DNX-based](http://aspnet.github.io/docfx/tutorial/docfx_getting_started.html#use-docfx-under-dnx) version of the tool to be able to invoke it from the command line; if you are comfortable with other ways listed on the link above, feel free to use those. \n+There are several ways to use DocFX, and most of them are covered in the DocFX [getting started guide](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html). \n+This small guide will use the [command-line based](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool) version of the tool. \n+If you are comfortable with other ways listed on the link above, feel free to use those. \n \n-**Note:** please note that as of now, docfx requires the full .NET Framework (Windows) or Mono (Linux/OSX). We will be working towards porting it to .NET Core in the future. \n+**Note:** please note that as of now, DocFX requires the .NET Framework on Windows or Mono for Linux or macOS. We will be working towards porting it to .NET Core in the future. \n \n The conceptual documentation is placed in the docs folder in the root of the repo so most of the work will happen there. \n \n-Using the DNX-based docfx tool, you build the resulting \n+You can build and preview the resulting site locally using a built-in web server.\n \n-\tdocfx build\n+\tdocfx core-docs\\docfx.json --serve\n \t\n-After build completes, you can preview the resulting site locally using built-in web server.\n+This will start the local preview on [localhost:8080](http://localhost:8080). You can then view the changes by going to http://localhost:8080/docs/[path] (for example, http://localhost:8080/docs/about/).","path":"CONTRIBUTING.md","position":137,"original_position":137,"commit_id":"878a32c2bf1ea165f9ea1dd68a14802bd9aa7948","original_commit_id":"878a32c2bf1ea165f9ea1dd68a14802bd9aa7948","user":{"login":"svick","id":287848,"avatar_url":"https://avatars.githubusercontent.com/u/287848?v=3","gravatar_id":"","url":"https://api.github.com/users/svick","html_url":"https://github.com/svick","followers_url":"https://api.github.com/users/svick/followers","following_url":"https://api.github.com/users/svick/following{/other_user}","gists_url":"https://api.github.com/users/svick/gists{/gist_id}","starred_url":"https://api.github.com/users/svick/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/svick/subscriptions","organizations_url":"https://api.github.com/users/svick/orgs","repos_url":"https://api.github.com/users/svick/repos","events_url":"https://api.github.com/users/svick/events{/privacy}","received_events_url":"https://api.github.com/users/svick/received_events","type":"User","site_admin":false},"body":"GitHub interprets this as an invalid link, so this:\r\n\r\n```md\r\nYou can then view the changes by going to http://localhost:8080/docs/[path] (for example, http://localhost:8080/docs/about/).\r\n```\r\n\r\nrenders as:\r\n\r\n> You can then view the changes by going to http://localhost:8080/docs/path.","created_at":"2016-06-27T10:10:14Z","updated_at":"2016-06-27T10:10:14Z","html_url":"https://github.com/dotnet/core-docs/pull/668#discussion_r68552011","pull_request_url":"https://api.github.com/repos/dotnet/core-docs/pulls/668","_links":{"self":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/comments/68552011"},"html":{"href":"https://github.com/dotnet/core-docs/pull/668#discussion_r68552011"},"pull_request":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/668"}}},"pull_request":{"url":"https://api.github.com/repos/dotnet/core-docs/pulls/668","id":75274854,"html_url":"https://github.com/dotnet/core-docs/pull/668","diff_url":"https://github.com/dotnet/core-docs/pull/668.diff","patch_url":"https://github.com/dotnet/core-docs/pull/668.patch","issue_url":"https://api.github.com/repos/dotnet/core-docs/issues/668","number":668,"state":"open","locked":false,"title":"changes to contribution guide","user":{"login":"mairaw","id":12971179,"avatar_url":"https://avatars.githubusercontent.com/u/12971179?v=3","gravatar_id":"","url":"https://api.github.com/users/mairaw","html_url":"https://github.com/mairaw","followers_url":"https://api.github.com/users/mairaw/followers","following_url":"https://api.github.com/users/mairaw/following{/other_user}","gists_url":"https://api.github.com/users/mairaw/gists{/gist_id}","starred_url":"https://api.github.com/users/mairaw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mairaw/subscriptions","organizations_url":"https://api.github.com/users/mairaw/orgs","repos_url":"https://api.github.com/users/mairaw/repos","events_url":"https://api.github.com/users/mairaw/events{/privacy}","received_events_url":"https://api.github.com/users/mairaw/received_events","type":"User","site_admin":false},"body":"/cc @richlander @blackdwarf ","created_at":"2016-06-27T08:45:00Z","updated_at":"2016-06-27T10:10:14Z","closed_at":null,"merged_at":null,"merge_commit_sha":"37a1267eb99ff1174e3ba114b785bed3a38dba17","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/dotnet/core-docs/pulls/668/commits","review_comments_url":"https://api.github.com/repos/dotnet/core-docs/pulls/668/comments","review_comment_url":"https://api.github.com/repos/dotnet/core-docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/dotnet/core-docs/issues/668/comments","statuses_url":"https://api.github.com/repos/dotnet/core-docs/statuses/878a32c2bf1ea165f9ea1dd68a14802bd9aa7948","head":{"label":"dotnet:contribguide","ref":"contribguide","sha":"878a32c2bf1ea165f9ea1dd68a14802bd9aa7948","user":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"repo":{"id":35890081,"name":"core-docs","full_name":"dotnet/core-docs","owner":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/dotnet/core-docs","description":".NET Core documentation (work in progress).","fork":false,"url":"https://api.github.com/repos/dotnet/core-docs","forks_url":"https://api.github.com/repos/dotnet/core-docs/forks","keys_url":"https://api.github.com/repos/dotnet/core-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/dotnet/core-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/dotnet/core-docs/teams","hooks_url":"https://api.github.com/repos/dotnet/core-docs/hooks","issue_events_url":"https://api.github.com/repos/dotnet/core-docs/issues/events{/number}","events_url":"https://api.github.com/repos/dotnet/core-docs/events","assignees_url":"https://api.github.com/repos/dotnet/core-docs/assignees{/user}","branches_url":"https://api.github.com/repos/dotnet/core-docs/branches{/branch}","tags_url":"https://api.github.com/repos/dotnet/core-docs/tags","blobs_url":"https://api.github.com/repos/dotnet/core-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/dotnet/core-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/dotnet/core-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/dotnet/core-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/dotnet/core-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/dotnet/core-docs/languages","stargazers_url":"https://api.github.com/repos/dotnet/core-docs/stargazers","contributors_url":"https://api.github.com/repos/dotnet/core-docs/contributors","subscribers_url":"https://api.github.com/repos/dotnet/core-docs/subscribers","subscription_url":"https://api.github.com/repos/dotnet/core-docs/subscription","commits_url":"https://api.github.com/repos/dotnet/core-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/dotnet/core-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/dotnet/core-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/dotnet/core-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/dotnet/core-docs/contents/{+path}","compare_url":"https://api.github.com/repos/dotnet/core-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/dotnet/core-docs/merges","archive_url":"https://api.github.com/repos/dotnet/core-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/dotnet/core-docs/downloads","issues_url":"https://api.github.com/repos/dotnet/core-docs/issues{/number}","pulls_url":"https://api.github.com/repos/dotnet/core-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/dotnet/core-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/dotnet/core-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/dotnet/core-docs/labels{/name}","releases_url":"https://api.github.com/repos/dotnet/core-docs/releases{/id}","deployments_url":"https://api.github.com/repos/dotnet/core-docs/deployments","created_at":"2015-05-19T15:13:32Z","updated_at":"2016-06-26T19:58:36Z","pushed_at":"2016-06-27T10:02:51Z","git_url":"git://github.com/dotnet/core-docs.git","ssh_url":"git@github.com:dotnet/core-docs.git","clone_url":"https://github.com/dotnet/core-docs.git","svn_url":"https://github.com/dotnet/core-docs","homepage":"https://dotnet.github.io/docs/index.html","size":16648,"stargazers_count":115,"watchers_count":115,"language":"PowerShell","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":145,"mirror_url":null,"open_issues_count":146,"forks":145,"open_issues":146,"watchers":115,"default_branch":"master"}},"base":{"label":"dotnet:master","ref":"master","sha":"2aec790ad37acc2b6783aa42d6551267d8d486c6","user":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"repo":{"id":35890081,"name":"core-docs","full_name":"dotnet/core-docs","owner":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/dotnet/core-docs","description":".NET Core documentation (work in progress).","fork":false,"url":"https://api.github.com/repos/dotnet/core-docs","forks_url":"https://api.github.com/repos/dotnet/core-docs/forks","keys_url":"https://api.github.com/repos/dotnet/core-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/dotnet/core-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/dotnet/core-docs/teams","hooks_url":"https://api.github.com/repos/dotnet/core-docs/hooks","issue_events_url":"https://api.github.com/repos/dotnet/core-docs/issues/events{/number}","events_url":"https://api.github.com/repos/dotnet/core-docs/events","assignees_url":"https://api.github.com/repos/dotnet/core-docs/assignees{/user}","branches_url":"https://api.github.com/repos/dotnet/core-docs/branches{/branch}","tags_url":"https://api.github.com/repos/dotnet/core-docs/tags","blobs_url":"https://api.github.com/repos/dotnet/core-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/dotnet/core-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/dotnet/core-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/dotnet/core-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/dotnet/core-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/dotnet/core-docs/languages","stargazers_url":"https://api.github.com/repos/dotnet/core-docs/stargazers","contributors_url":"https://api.github.com/repos/dotnet/core-docs/contributors","subscribers_url":"https://api.github.com/repos/dotnet/core-docs/subscribers","subscription_url":"https://api.github.com/repos/dotnet/core-docs/subscription","commits_url":"https://api.github.com/repos/dotnet/core-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/dotnet/core-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/dotnet/core-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/dotnet/core-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/dotnet/core-docs/contents/{+path}","compare_url":"https://api.github.com/repos/dotnet/core-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/dotnet/core-docs/merges","archive_url":"https://api.github.com/repos/dotnet/core-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/dotnet/core-docs/downloads","issues_url":"https://api.github.com/repos/dotnet/core-docs/issues{/number}","pulls_url":"https://api.github.com/repos/dotnet/core-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/dotnet/core-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/dotnet/core-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/dotnet/core-docs/labels{/name}","releases_url":"https://api.github.com/repos/dotnet/core-docs/releases{/id}","deployments_url":"https://api.github.com/repos/dotnet/core-docs/deployments","created_at":"2015-05-19T15:13:32Z","updated_at":"2016-06-26T19:58:36Z","pushed_at":"2016-06-27T10:02:51Z","git_url":"git://github.com/dotnet/core-docs.git","ssh_url":"git@github.com:dotnet/core-docs.git","clone_url":"https://github.com/dotnet/core-docs.git","svn_url":"https://github.com/dotnet/core-docs","homepage":"https://dotnet.github.io/docs/index.html","size":16648,"stargazers_count":115,"watchers_count":115,"language":"PowerShell","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":145,"mirror_url":null,"open_issues_count":146,"forks":145,"open_issues":146,"watchers":115,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/668"},"html":{"href":"https://github.com/dotnet/core-docs/pull/668"},"issue":{"href":"https://api.github.com/repos/dotnet/core-docs/issues/668"},"comments":{"href":"https://api.github.com/repos/dotnet/core-docs/issues/668/comments"},"review_comments":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/668/comments"},"review_comment":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/dotnet/core-docs/pulls/668/commits"},"statuses":{"href":"https://api.github.com/repos/dotnet/core-docs/statuses/878a32c2bf1ea165f9ea1dd68a14802bd9aa7948"}}}}
{"actor":{"display_login":"svick"}}