Removed conflicts

CONTRIBUTING.md

@@ -1,66 +1,35 @@
 # How to Contribute
 
-We love Pull Requests! Your contributions help make Octokit great.
+Contributions take many forms from submitting issues, writing docs, to making
+code changes - we welcome it all!
 
 ## Getting Started
 
-So you want to contribute to Octokit. Great! Contributions take many forms 
-from submitting issues, writing docs, to making code changes. We welcome 
-it all. Don't forget to sign up for a [GitHub account](https://github.com/signup/free), 
-if you haven't already.
+If you don't have a GitHub account, you can [sign up](https://github.com/signup/free)
+as it will help you to participate with the project.
 
-## Getting Started
+If you are looking to contribute to the codebase, please ensure you have Visual
+Studio 2015 installed - you can download the Community edition from
+[here](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx)
 
-You can clone this repository locally from GitHub using the "Clone in Desktop" 
-button from the main project site, or run this command in the Git Shell:
+If you are running GitHub Desktop, you can clone this repository locally from
+GitHub using the "Clone in Desktop" button from the Octokit.net project page,
+or run this command in your Git-enabled shell:
 
-`git clone git@github.com:octokit/Octokit.net.git Octokit`
+`git clone https://github.com/octokit/Octokit.net.git Octokit`
 
-If you want to make contributions to the project, 
-[forking the project](https://help.github.com/articles/fork-a-repo) is the 
+If you want to make contributions to the project,
+[forking the project](https://help.github.com/articles/fork-a-repo) is the
 easiest way to do this. You can then clone down your fork instead:
 
-`git clone [email protected]:MY-USERNAME-HERE/Octokit.net.git Octokit`
-
-After doing that, run the `.\build.cmd` script at the root of the repository 
-to ensure all the tests pass.
-
-### How is the codebase organised?
-
-The two main projects are the `Octokit` and `Octokit.Reactive` projects.
-
-The `Octokit.Reactive` library is a thin wrapper over the `Octokit` 
-library - for those who want to use Reactive Extensions (Rx) instead of tasks.
-
-The namespaces are organised so that the relevant components are easy to discover:
-
- - **Authentication** - everything related to authenticating requests 
- - **Clients** - the logic for interacting with various parts of the GitHub API
- - **Exceptions** - types which represent exceptional behaviour from the API 
- - **Helpers** - assorted extensions and helpers to keep the code neat and tidy
- - **Http** - the internal networking components which Octokit requires
- - **Models** - types which represent request/response objects
-
-Unless you're modifying some core behaviour, the **Clients** and **Models** namespaces
-are likely to be the most interesting areas.
+`git clone https://github.com/MY-USERNAME-HERE/Octokit.net.git Octokit`
 
-The clients within a project are organized similarly to the endpoints in the
-[GitHub API documentation](http://developer.github.com/v3/)
+After doing that, run the `.\build` script at the root of the repository
+to ensure everything builds and the tests pass.
 
-Some clients are "sub-clients". For example, when you navigate to the
-[Issues API](http://developer.github.com/v3/issues/) you'll notice there's an
-endpoint for issues. But in the right navbar, there are other APIs such as
-[Assignees](http://developer.github.com/v3/issues/assignees/) and
-[Milestones](http://developer.github.com/v3/issues/milestones/).
+## How can I get involved?
 
-We've tried to mirror this structure. So the `IObservableMilestoneClient` isn't
-a direct property of `IObservableGitHubClient`. Instead, it's a property of the
-`IObservableIssuesClient`. And thus you can get to it by going to
-`client.Issues.Milestones`.
-
-### What needs to be done?
-
-We have a [`easy-fix`](https://github.com/octokit/octokit.net/issues?labels=easy-fix&state=open)
+We have an [`up-for-grabs`](https://github.com/octokit/octokit.net/issues/labels/up-for-grabs)
 tag on our issue tracker to indicate tasks which contributors can pick up.
 
 If you've found something you'd like to contribute to, leave a comment in the issue
@@ -72,28 +41,63 @@ for ways to improve the API to make it easy to work with the GitHub API.
 
 ## Making Changes
 
-When you're ready to make a change, 
-[create a branch](https://help.github.com/articles/fork-a-repo#create-branches) 
-off the `master` branch. We use `master` as the default branch for the 
-repository, and it holds the most recent contributions, so any changes you make
-in master might cause conflicts down the track.
+When you're ready to make a change, create a branch off the `master` branch:
+
+```
+git checkout master
+git pull origin master
+git checkout -b SOME-BRANCH-NAME
+```
+
+We use `master` as the default branch for the repository, and it holds the most
+recent contributions. By working in a branch away from `master` you can handle
+potential conflicts that may occur in the future.
 
 If you make focused commits (instead of one monolithic commit) and have descriptive
 commit messages, this will help speed up the review process.
 
-If you're adding new files to the Octokit project, we have a helper script to
-synchronize these changes with the Mono* projects in the solution. 
+### Adding New files
+
+To ensure new files are available in the various projects, we have a helper script
+to synchronize these changes across all the projects in the solution.
+
+If you need to create new files:
+
+  - add the file to the main `Octokit` project
+  - build the project (to ensure the `csproj` change is saved)
+  - run this command: `.\build FixProjects`
 
-Just run this command: `.\build FixProjects`
+At any time you can build the project with `.\build BuildApp` - this will also
+run FxCop analysis.
+
+### Running Tests
 
 Octokit.net also has a suite of tests which you can run to ensure existing
-behaviour is unchanged. If you're adding new features, please add some 
-tests alongside so the maintainers can sleep at night, knowing their 
+behaviour is not affected. If you're adding new features, please add some
+tests alongside so the maintainers can sleep at night, knowing their
 safety blanket is nice and green!
 
-Run this command to confirm all the tests pass: `.\build`
+The test suite is arranged into fast and slow tests.
+
+#### Fast Tests
+
+**Unit Tests:** `.\build UnitTests`
+
+These tests verify specific behaviour while being isolated from the rest of the
+library. If you are not familiar with unit testing, have a look at the existing
+examples - they should be easy to apply to your work.
+
+**Convention Tests:** `.\build ConventionTests`
+
+These tests verify conventions and structure across the entire codebase -
+ensuring everything is consistent and predictable. When writing new features,
+these tests may fail and should help indicate where the changes have violated
+the conventions, so feel free to run them locally while you're working on new
+features.
+
+#### Slow Tests
 
-### Running integration tests
+**Integration Tests**
 
 Octokit has integration tests that access the GitHub API, but they require a
 bit of setup to run. The tests make use of a set of test accounts accessed via
@@ -104,9 +108,23 @@ variables:
 
 `.\script\configure-integration-tests.ps1`
 
-Once these are set, the integration tests will be executed both when 
-running the IntegrationTests build target, or when running the 
-Octokit.Tests.Integration assembly in the Visual Studio test runner.
+After running this, ensure any existing instances of Visual Studio are restarted
+so they pick up the new environment variables are detected.
+
+With these variables set, you can run the integration tests locally using
+`.\build IntegrationTests` or by running the `Octokit.Tests.Integration`
+assembly in the Visual Studio test runner.
+
+**Note:** as the integration tests rely on using the actual GitHub API, you may
+encounter issues if running the tests too frequently. Please use a test account
+so that you're not impacted in the unlikely scenario of your account being
+flagged as a spammer.
+
+### Testing Documentation
+
+If you are making changes to the documentation for Octokit, you can test these
+changes locally using the [guide](https://github.com/shiftkey/octokit.net/blob/rewrite-contributing/docs/contributing.md)
+under the `docs` folder.
 
 ### Submitting Changes
 
@@ -116,29 +134,34 @@ the Git Shell:
 `git push origin MY-BRANCH-NAME`
 
 Once your changes are ready to be reviewed, publish the branch to GitHub and
-[open a pull request](https://help.github.com/articles/using-pull-requests) 
+[open a pull request](https://help.github.com/articles/using-pull-requests)
 against it.
 
-A few little tips with pull requests:
+A few suggestions when opening a pull request:
 
- - prefix the title with `[WIP]` to indicate this is a work-in-progress. It's
-   always good to get feedback early, so don't be afraid to open the PR before it's "done".
- - use [checklists](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments) 
-   to indicate the tasks which need to be done, so everyone knows how close you are to done.
- - add comments to the PR about things that are unclear or you would like suggestions on
+ - if you are addressing a particular issue, reference it like this:
+
+>   Fixes #1145
 
-Don't forget to mention in the pull request description which issue/issues are 
-being addressed.
+ - prefix the title with `[WIP]` to indicate this is a work-in-progress. It's
+   always good to get feedback early, so don't be afraid to open the PR before
+   it's "done".
+ - use [checklists](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
+   to indicate the tasks which need to be done, so everyone knows how close you
+   are to done.
+ - add comments to the PR about things that are unclear or you would like
+   suggestions on
 
-Some things that will increase the chance that your pull request is accepted.
+Some things that will increase the chance that your pull request is accepted:
 
 * Follow existing code conventions. Most of what we do follows [standard .NET
   conventions](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md) except in a few places. We include a ReSharper team settings file.
-* Include unit tests that would otherwise fail without your code, but pass with 
+* Include unit tests that would otherwise fail without your code, but pass with
   it.
-* Update the documentation, the surrounding one, examples elsewhere, guides, 
+* Update the documentation, the surrounding one, examples elsewhere, guides,
   whatever is affected by your contribution
 
 # Additional Resources
 
+* [Octokit Codebase Overview](https://github.com/octokit/octokit.net/blob/master/OVERVIEW.md)
 * [General GitHub documentation](http://help.github.com/)

OVERVIEW.md

@@ -0,0 +1,32 @@
+### How is the codebase organised?
+
+The two main projects are the `Octokit` and `Octokit.Reactive` projects.
+
+The `Octokit.Reactive` library is a thin wrapper over the `Octokit`
+library - for those who want to use Reactive Extensions (Rx) instead of tasks.
+
+The namespaces are organised so that the relevant components are easy to discover:
+
+ - **Authentication** - everything related to authenticating requests
+ - **Clients** - the logic for interacting with various parts of the GitHub API
+ - **Exceptions** - types which represent exceptional behaviour from the API
+ - **Helpers** - assorted extensions and helpers to keep the code neat and tidy
+ - **Http** - the internal networking components which Octokit requires
+ - **Models** - types which represent request/response objects
+
+Unless you're modifying some core behaviour, the **Clients** and **Models** namespaces
+are likely to be the most interesting areas.
+
+The clients within a project are organized similarly to the endpoints in the
+[GitHub API documentation](http://developer.github.com/v3/)
+
+Some clients are "sub-clients". For example, when you navigate to the
+[Issues API](http://developer.github.com/v3/issues/) you'll notice there's an
+endpoint for issues. But in the right navbar, there are other APIs such as
+[Assignees](http://developer.github.com/v3/issues/assignees/) and
+[Milestones](http://developer.github.com/v3/issues/milestones/).
+
+We've tried to mirror this structure. So the `IObservableMilestoneClient` isn't
+a direct property of `IObservableGitHubClient`. Instead, it's a property of the
+`IObservableIssuesClient`. And thus you can get to it by going to
+`client.Issues.Milestones`.

Octokit.Reactive/Clients/IObservableAssigneesClient.cs

@@ -12,6 +12,15 @@ public interface IObservableAssigneesClient
         /// <returns></returns>
         IObservable<User> GetAllForRepository(string owner, string name);
 
+        /// <summary>
+        /// Gets all the available assignees (owner + collaborators) to which issues may be assigned.
+        /// </summary>
+        /// <param name="owner">The owner of the repository</param>
+        /// <param name="name">The name of the repository</param>
+        /// <param name="options">The options to change API's behaviour.</param>
+        /// <returns></returns>
+        IObservable<User> GetAllForRepository(string owner, string name, ApiOptions options);
+
         /// <summary>
         /// Checks to see if a user is an assignee for a repository.
         /// </summary>

Octokit.Reactive/Clients/IObservableReleasesClient.cs

@@ -18,6 +18,19 @@ public interface IObservableReleasesClient
         /// <returns>The list of <see cref="Release"/>s for the specified repository.</returns>
         IObservable<Release> GetAll(string owner, string name);
 
+        /// <summary>
+        /// Gets all <see cref="Release"/>s for the specified repository.
+        /// </summary>
+        /// <remarks>
+        /// See the <a href="http://developer.github.com/v3/repos/releases/#list-releases-for-a-repository">API documentation</a> for more information.
+        /// </remarks>
+        /// <param name="owner">The repository's owner</param>
+        /// <param name="name">The repository's name</param>
+        /// <param name="options">Options for changing the API response</param>
+        /// <exception cref="ApiException">Thrown when a general API error occurs.</exception>
+        /// <returns>The list of <see cref="Release"/>s for the specified repository.</returns>
+        IObservable<Release> GetAll(string owner, string name, ApiOptions options);
+
         /// <summary>
         /// Gets a single <see cref="Release"/> for the specified repository.
         /// </summary>

Octokit.Reactive/Clients/IObservableUserEmailsClient.cs

@@ -22,6 +22,17 @@ public interface IObservableUserEmailsClient
         [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
         IObservable<EmailAddress> GetAll();
 
+        /// <summary>
+        /// Gets all email addresses for the authenticated user.
+        /// </summary>
+        /// <remarks>
+        /// http://developer.github.com/v3/users/emails/#list-email-addresses-for-a-user
+        /// </remarks>
+        /// <param name="options">Options for changing the API response</param>
+        /// <returns>The <see cref="EmailAddress"/>es for the authenticated user.</returns>
+        [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
+        IObservable<EmailAddress> GetAll(ApiOptions options);
+
         /// <summary>
         /// Adds email addresses for the authenticated user.
         /// </summary>

Octokit.Reactive/Clients/IObservableUserKeysClient.cs

@@ -19,7 +19,8 @@ public interface IObservableUserKeysClient
         /// https://developer.github.com/v3/users/keys/#list-your-public-keys
         /// </remarks>
         /// <returns></returns>
-        IObservable<PublicKey> GetAll();
+        [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
+        IObservable<PublicKey> GetAllForCurrent();
 
         /// <summary>
         /// Gets all verified public keys for a user.

Octokit.Reactive/Clients/ObservableAssigneesClient.cs

@@ -31,6 +31,22 @@ public IObservable<User> GetAllForRepository(string owner, string name)
             return _connection.GetAndFlattenAllPages<User>(ApiUrls.Assignees(owner, name));
         }
 
+        /// <summary>
+        /// Gets all the available assignees (owner + collaborators) to which issues may be assigned.
+        /// </summary>
+        /// <param name="owner">The owner of the repository</param>
+        /// <param name="name">The name of the repository</param>
+        /// <param name="options">The options to change API's behaviour</param>
+        /// <returns></returns>
+        public IObservable<User> GetAllForRepository(string owner, string name, ApiOptions options)
+        {
+            Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
+            Ensure.ArgumentNotNullOrEmptyString(name, "name");
+            Ensure.ArgumentNotNull(options, "options");
+
+            return _connection.GetAndFlattenAllPages<User>(ApiUrls.Assignees(owner, name), options);
+        }
+
         /// <summary>
         /// Checks to see if a user is an assignee for a repository.
         /// </summary>

Octokit.Reactive/Clients/ObservableReleasesClient.cs

@@ -36,6 +36,26 @@ public IObservable<Release> GetAll(string owner, string name)
             return _connection.GetAndFlattenAllPages<Release>(ApiUrls.Releases(owner, name));
         }
 
+        /// <summary>
+        /// Gets all <see cref="Release"/>s for the specified repository.
+        /// </summary>
+        /// <remarks>
+        /// See the <a href="http://developer.github.com/v3/repos/releases/#list-releases-for-a-repository">API documentation</a> for more information.
+        /// </remarks>
+        /// <param name="owner">The repository's owner</param>
+        /// <param name="name">The repository's name</param>
+        /// <param name="options">Options for changing the API response</param>
+        /// <exception cref="ApiException">Thrown when a general API error occurs.</exception>
+        /// <returns>The list of <see cref="Release"/>s for the specified repository.</returns>
+        public IObservable<Release> GetAll(string owner, string name, ApiOptions options)
+        {
+            Ensure.ArgumentNotNullOrEmptyString(owner, "owner");
+            Ensure.ArgumentNotNullOrEmptyString(name, "name");
+            Ensure.ArgumentNotNull(options, "options");
+
+            return _connection.GetAndFlattenAllPages<Release>(ApiUrls.Releases(owner, name), options);
+        }
+
         /// <summary>
         /// Gets a single <see cref="Release"/> for the specified repository.
         /// </summary>