Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes grammar and style #1356

Merged
merged 2 commits into from
May 24, 2022
Merged

Fixes grammar and style #1356

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ff7333
Fixes grammar and style
nikoandpiko Aug 15, 2021
a540a75
Merge branch '4-stable' into readme-style-update
nickfloyd May 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 58 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ When passing additional parameters to GET based request use the following syntax
client.contents('octokit/octokit.rb', path: 'path/to/file.rb', query: {ref: 'some-other-branch'})
```

[API methods]: http://octokit.github.io/octokit.rb/method_list.html
[api methods]: http://octokit.github.io/octokit.rb/method_list.html
nickfloyd marked this conversation as resolved.
Show resolved Hide resolved

## Consuming resources

Expand Down Expand Up @@ -182,6 +182,7 @@ user = client.user
user.login
# => "defunkt"
```

While Basic Authentication allows you to get started quickly, OAuth access
tokens are the preferred way to authenticate on behalf of users.

Expand All @@ -190,9 +191,9 @@ tokens are the preferred way to authenticate on behalf of users.
[OAuth access tokens][oauth] provide two main benefits over using your username
and password:

* **Revokable access**. Access tokens can be revoked, removing access for only
- **Revocable access**. Access tokens can be revoked, removing access for only
that token without having to change your password everywhere.
* **Limited access**. Access tokens have [access scopes][] which allow for more
- **Limited access**. Access tokens have [access scopes][] which allow for more
granular access to API resources. For instance, you can grant a third party
access to your gists but not your private repositories.

Expand Down Expand Up @@ -231,7 +232,7 @@ client = Octokit::Client.new \
user = client.user("defunkt", :headers => { "X-GitHub-OTP" => "<your 2FA token>" })
```

As you can imagine, this gets annoying quick since two-factor auth tokens are very short lived. So it is recommended to create an oauth token for the user to communicate with the API:
As you can imagine, this gets annoying quickly since two-factor auth tokens are very short lived. So it is recommended to create an oauth token for the user to communicate with the API:

```ruby
client = Octokit::Client.new \
Expand All @@ -246,20 +247,22 @@ client.create_authorization(:scopes => ["user"], :note => "Name of token",
### Using a .netrc file

Octokit supports reading credentials from a netrc file (defaulting to
`~/.netrc`). Given these lines in your netrc:
`~/.netrc`). Given these lines in your netrc:

```
machine api.github.com
login defunkt
password c0d3b4ssssss!
```

You can now create a client with those credentials:

```ruby
client = Octokit::Client.new(:netrc => true)
client.login
# => "defunkt"
```

But _I want to use OAuth_ you say. Since the GitHub API supports using an OAuth
token as a Basic password, you totally can:

Expand Down Expand Up @@ -348,7 +351,7 @@ With a bit of setup, you can also use Octokit with your GitHub Enterprise instan

To interact with the "regular" GitHub.com APIs in GitHub Enterprise, simply configure the `api_endpoint` to match your hostname. For example:

``` ruby
```ruby
Octokit.configure do |c|
c.api_endpoint = "https://<hostname>/api/v3/"
end
Expand All @@ -360,7 +363,7 @@ client = Octokit::Client.new(:access_token => "<your 40 char token>")

The GitHub Enterprise Admin APIs are under a different client: `EnterpriseAdminClient`. You'll need to have an administrator account in order to use these APIs.

``` ruby
```ruby
admin_client = Octokit::EnterpriseAdminClient.new(
:access_token => "<your 40 char token>",
:api_endpoint => "https://<hostname>/api/v3/"
Expand All @@ -377,9 +380,9 @@ admin_client = Octokit.enterprise_admin_client.new

### Interacting with the GitHub Enterprise Management Console APIs

The GitHub Enterprise Management Console APIs are also under a separate client: `EnterpriseManagementConsoleClient`. In order to use it, you'll need to provide both your management console password as well as the endpoint to your management console. This is different than the API endpoint provided above.
The GitHub Enterprise Management Console APIs are also under a separate client: `EnterpriseManagementConsoleClient`. In order to use it, you'll need to provide both your management console password as well as the endpoint to your management console. This is different from the API endpoint provided above.

``` ruby
```ruby
management_console_client = Octokit::EnterpriseManagementConsoleClient.new(
:management_console_password => "secret",
:management_console_endpoint = "https://hostname:8633"
Expand All @@ -396,9 +399,9 @@ management_console_client = Octokit.enterprise_management_console_client.new

### SSL Connection Errors

You *may* need to disable SSL temporarily while first setting up your GitHub Enterprise install. You can do that with the following configuration:
You _may_ need to disable SSL temporarily while first setting up your GitHub Enterprise install. You can do that with the following configuration:

``` ruby
```ruby
client.connection_options[:ssl] = { :verify => false }
```

Expand Down Expand Up @@ -463,6 +466,7 @@ Octokit.configure do |c|
}
end
```

You should set a timeout in order to avoid Ruby’s Timeout module, which can hose your server. Here are some resources for more information on this:

- [The Oldest Bug In Ruby - Why Rack::Timeout Might Hose your Server](https://www.schneems.com/2017/02/21/the-oldest-bug-in-ruby-why-racktimeout-might-hose-your-server/)
Expand Down Expand Up @@ -492,7 +496,7 @@ repos.last.name
# => "faraday-zeromq"
```

When processing API responses, all `*_url` attributes are culled in to the link
When processing API responses, all `*_url` attributes are culled into the link
relations collection. Any `url` attribute becomes `.rels[:self]`.

### URI templates
Expand Down Expand Up @@ -528,17 +532,17 @@ Octokit 3.0 aims to be hypermedia-driven, removing the internal URL
construction currently used throughout the client.

[hypermedia]: http://en.wikipedia.org/wiki/Hypermedia
[Sawyer]: https://github.com/lostisland/sawyer
[Faraday]: https://github.com/lostisland/faraday
[sawyer]: https://github.com/lostisland/sawyer
[faraday]: https://github.com/lostisland/faraday
[uri-templates]: http://tools.ietf.org/html/rfc6570

## Upgrading guide

Version 4.0

- **removes support for a [long-deprecated overload][list-pulls] for
passing state as a positional argument** when listing pull requests. Instead,
pass `state` in the method options.
passing state as a positional argument** when listing pull requests. Instead,
pass `state` in the method options.
- **drops support for Ruby < 2.0**.
- adds support for new [Enterprise-only APIs](#working-with-github-enterprise).
- adds support for [Repository redirects][redirects].
Expand All @@ -555,6 +559,7 @@ for the client:
```ruby
Octokit.default_media_type = "application/vnd.github.beta+json"
```

or per-request

```ruby
Expand All @@ -571,21 +576,20 @@ Version 2.0 includes a completely rewritten `Client` factory that now memoizes
client instances based on unique configuration options. Breaking changes also
include:

* `:oauth_token` is now `:access_token`
* `:auto_traversal` is now `:auto_paginate`
* `Hashie::Mash` has been removed. Responses now return a `Sawyer::Resource`
- `:oauth_token` is now `:access_token`
- `:auto_traversal` is now `:auto_paginate`
- `Hashie::Mash` has been removed. Responses now return a `Sawyer::Resource`
object. This new type behaves mostly like a Ruby `Hash`, but does not fully
support the `Hashie::Mash` API.
* Two new client error types are raised where appropriate:
- Two new client error types are raised where appropriate:
`Octokit::TooManyRequests` and `Octokit::TooManyLoginAttempts`
* The `search_*` methods from v1.x are now found at `legacy_search_*`
* Support for netrc requires including the [netrc gem][] in your Gemfile or
- The `search_*` methods from v1.x are now found at `legacy_search_*`
- Support for netrc requires including the [netrc gem][] in your Gemfile or
gemspec.
* DateTime fields are now proper `DateTime` objects. Previous versions outputted DateTime fields as 'String' objects.
- DateTime fields are now proper `DateTime` objects. Previous versions outputted DateTime fields as 'String' objects.

[netrc gem]: https://rubygems.org/gems/netrc


## Advanced usage

Since Octokit employs [Faraday][faraday] under the hood, some behavior can be
Expand Down Expand Up @@ -613,6 +617,7 @@ Octokit.middleware = stack
client = Octokit::Client.new
client.user 'pengwynn'
```

```
I, [2013-08-22T15:54:38.583300 #88227] INFO -- : get https://api.github.com/users/pengwynn
D, [2013-08-22T15:54:38.583401 #88227] DEBUG -- request: Accept: "application/vnd.github.beta+json"
Expand Down Expand Up @@ -656,7 +661,6 @@ Once configured, the middleware will store responses in cache based on ETag
fingerprint and serve those back up for future `304` responses for the same
resource. See the [project README][cache] for advanced usage.


[cache]: https://github.com/plataformatec/faraday-http-cache
[faraday]: https://github.com/lostisland/faraday

Expand All @@ -672,12 +676,11 @@ to run a Ruby console to poke on Octokit, you can crank one up with:

script/console

Using the scripts in `./script` instead of `bundle exec rspec`, `bundle
console`, etc. ensures your dependencies are up-to-date.
Using the scripts in `./script` instead of `bundle exec rspec`, `bundle console`, etc. ensures your dependencies are up-to-date.

### Code of Conduct

We want both the Octokit.rb and larger Octokit communities to be an open
We want both the Octokit.rb and larger Octokit communities to be open
and welcoming environments. Please read and follow both in spirit and
letter [Code of Conduct](CODE_OF_CONDUCT.md).

Expand All @@ -694,52 +697,52 @@ Octokit uses environmental variables for storing credentials used in testing.
If you are testing an API endpoint that doesn't require authentication, you
can get away without any additional configuration. For the most part, tests
use an authenticated client, using a token stored in `ENV['OCTOKIT_TEST_GITHUB_TOKEN']`.
There are several different authenticating method's used across the api.
There are several different authentication methods used across the api.
Here is the full list of configurable environmental variables for testing
Octokit:

ENV Variable | Description |
:-------------------|:-----------------|
`OCTOKIT_TEST_GITHUB_LOGIN`| GitHub login name (preferably one created specifically for testing against).
`OCTOKIT_TEST_GITHUB_PASSWORD`| Password for the test GitHub login.
`OCTOKIT_TEST_GITHUB_TOKEN` | [Personal Access Token](https://github.com/blog/1509-personal-api-tokens) for the test GitHub login.
`OCTOKIT_TEST_GITHUB_CLIENT_ID` | Test OAuth application client id.
`OCTOKIT_TEST_GITHUB_CLIENT_SECRET` | Test OAuth application client secret.
`OCTOKIT_TEST_GITHUB_REPOSITORY` | Test repository to perform destructive actions against, this should not be set to any repository of importance. **Automatically created by the test suite if nonexistent** Default: `api-sandbox`
`OCTOKIT_TEST_GITHUB_ORGANIZATION` | Test organization.
`OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN` | GitHub Enterprise login name.
`OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN` | GitHub Enterprise token.
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password.
`OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT` | GitHub Enterprise hostname.
`OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint.
`OCTOKIT_TEST_GITHUB_INTEGRATION` | [GitHub Integration](https://developer.github.com/early-access/integrations/) owned by your test organization.
`OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION` | Installation of the GitHub Integration specified above.
`OCTOKIT_TEST_INTEGRATION_PEM_KEY` | File path to the private key generated from your integration.
| ENV Variable | Description |
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OCTOKIT_TEST_GITHUB_LOGIN` | GitHub login name (preferably one created specifically for testing against). |
| `OCTOKIT_TEST_GITHUB_PASSWORD` | Password for the test GitHub login. |
| `OCTOKIT_TEST_GITHUB_TOKEN` | [Personal Access Token](https://github.com/blog/1509-personal-api-tokens) for the test GitHub login. |
| `OCTOKIT_TEST_GITHUB_CLIENT_ID` | Test OAuth application client id. |
| `OCTOKIT_TEST_GITHUB_CLIENT_SECRET` | Test OAuth application client secret. |
| `OCTOKIT_TEST_GITHUB_REPOSITORY` | Test repository to perform destructive actions against, this should not be set to any repository of importance. **Automatically created by the test suite if nonexistent** Default: `api-sandbox` |
| `OCTOKIT_TEST_GITHUB_ORGANIZATION` | Test organization. |
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN` | GitHub Enterprise login name. |
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN` | GitHub Enterprise token. |
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD` | GitHub Enterprise management console password. |
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT` | GitHub Enterprise hostname. |
| `OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT` | GitHub Enterprise Management Console endpoint. |
| `OCTOKIT_TEST_GITHUB_INTEGRATION` | [GitHub Integration](https://developer.github.com/early-access/integrations/) owned by your test organization. |
| `OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION` | Installation of the GitHub Integration specified above. |
| `OCTOKIT_TEST_INTEGRATION_PEM_KEY` | File path to the private key generated from your integration. |

Since we periodically refresh our cassettes, please keep some points in mind
when writing new specs.

* **Specs should be idempotent**. The HTTP calls made during a spec should be
- **Specs should be idempotent**. The HTTP calls made during a spec should be
able to be run over and over. This means deleting a known resource prior to
creating it if the name has to be unique.
* **Specs should be able to be run in random order.** If a spec depends on
- **Specs should be able to be run in random order.** If a spec depends on
another resource as a fixture, make sure that's created in the scope of the
spec and not depend on a previous spec to create the data needed.
* **Do not depend on authenticated user info.** Instead of asserting
- **Do not depend on authenticated user info.** Instead of asserting
actual values in resources, try to assert the existence of a key or that a
response is an Array. We're testing the client, not the API.

[bootstrapping]: http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency
[VCR]: https://github.com/vcr/vcr
[vcr]: https://github.com/vcr/vcr

## Supported Ruby Versions

This library aims to support and is [tested against][actions] the following Ruby
implementations:

* Ruby 2.5
* Ruby 2.6
* Ruby 2.7
- Ruby 2.5
- Ruby 2.6
- Ruby 2.7

If something doesn't work on one of these Ruby versions, it's a bug.

Expand Down Expand Up @@ -776,7 +779,8 @@ The changes made between versions can be seen on the [project releases page][rel
[releases]: https://github.com/octokit/octokit.rb/releases

## Making Repeating Requests
In most cases it would be best to use a [webhooks](https://developer.github.com/webhooks/), but sometimes webhooks don't provide all of the information needed. In those cases where one might need to poll for progress or retry a request on failure, we designed [Octopoller](https://github.com/octokit/octopoller.rb). Octopoller is a micro gem perfect for making repeating requests.

In most cases it would be best to use [webhooks](https://developer.github.com/webhooks/), but sometimes webhooks don't provide all of the information needed. In those cases where one might need to poll for progress or retry a request on failure, we designed [Octopoller](https://github.com/octokit/octopoller.rb). Octopoller is a micro gem perfect for making repeating requests.

```ruby
Octopoller.poll(timeout: 15.seconds) do
Expand Down