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

Update Documentation Ahead Of Project Transfer #587

Merged
merged 1 commit into from
Nov 4, 2020
Merged

Update Documentation Ahead Of Project Transfer #587

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
76 changes: 76 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to make participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies within all project spaces, and it also applies when
an individual is representing the project or its community in public spaces.
Examples of representing a project or community include using an official
project e-mail address, posting via an official social media account, or acting
as an appointed representative at an online or offline event. Representation of
a project may be further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at [email protected]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq
147 changes: 147 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
## Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE.md).

Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

## Submitting a pull request

0. Fork and clone the repository
0. Create a new branch: `git checkout -b my-branch-name`
0. Make your change, add tests, and make sure the tests still pass
0. Push to your fork and submit a pull request
0. Pat your self on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

- Discuss your changes with the community in an issue.
- Allow your pull request to receive edits by maintainers.
- Write tests.
- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

## Automated And Manual Testing

### Overview

When raising a pull request against this project, automated tests will be launched to run our test suite.

In line with Terraform Provider testing best practices, these tests exercise against a live, public GitHub deployment (referred to as `dotcom`). Tests may also run against an Enterprise GitHub deployment (referred to as `ghes`), which is sometimes available during parts of a month. If your change requires testing against a specific version of GitHub, please let a maintainer know and this may be arranged.


### Building The Provider

Clone the provider
```sh
$ git clone [email protected]:terraform-providers/terraform-provider-github.git
```

Enter the provider directory and build the provider

```sh
$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-github
$ make build
# or if you're on a mac:
$ gnumake build
```

### Developing The Provider

If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.11+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`.

To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.

```sh
$ make build
...
$ $GOPATH/bin/terraform-provider-github
...
```

In order to test the provider, you can simply run `make test`.

```sh
$ make test
```

In order to run the full suite of Acceptance tests, run `make testacc`.

*Note:* Acceptance tests create real resources, and often cost money to run.

```sh
# run all tests through `make`
$ make testacc
# run all tests directly
$ go test -v ./...
# run specific test
$ go test -v ./... -run TestAccProviderConfigure
```

Commonly required environment variables are listed below:

```console
export TF_LOG=DEBUG
export GITHUB_ORGANIZATION=
export GITHUB_BASE_URL=
export GITHUB_OWNER=
export GITHUB_TEST_OWNER=
export GITHUB_TEST_ORGANIZATION=
export GITHUB_TEST_USER_TOKEN=
```

See [this project](https://github.com/terraformtesting/acceptance-tests) for more information on how tests are run automatically.

### GitHub Personal Access Token

You will need to create a [personal access token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) for
testing. It will need to have the following scopes selected:
* repo
* admin:org
* admin:public_key
* admin:repo_hook
* admin:org_hook
* user
* delete_repo
* admin:gpg_key

Once the token has been created, it must be exported in your environment as `GITHUB_TOKEN`.

### GitHub Organization

If you do not have an organization already that you are comfortable running tests against, you will need to [create one](https://help.github.com/en/articles/creating-a-new-organization-from-scratch). The free "Team for Open Source" org type is fine for these tests. The name of the organization must then be exported in your environment as `GITHUB_OWNER`.

If you are interested in using and/or testing Github's [Team synchronization](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/synchronizing-teams-between-your-identity-provider-and-github) feature, please contact a maintainer as special arrangements can be made for your convenience.

### Test Repositories

In the pasts, tests required pre-existing repositories. The current test suite has been refreshed to have less dependencies like this. Developers would previously have had to set up the following fixtures manually:

In the organization you are using above, create the following test repositories:

* `test-repo`
* The description should be `Test description, used in GitHub Terraform provider acceptance test.`
* The website url should be `http://www.example.com`
* Create two topics within the repo named `test-topic` and `second-test-topic`
* In the repo settings, make sure all features and merge button options are enabled.
* Create a `test-branch` branch
* `test-repo-template`
* Configure the repository to be a [Template repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)
* Create a release on the repository with `tag = v1.0`

Export an environment variable corresponding to `GITHUB_TEMPLATE_REPOSITORY=test-repo-template`.

### GitHub Users

Export your github username (the one you used to create the personal access token above) as `GITHUB_TEST_USER`. You may need to export a different github username as `GITHUB_TEST_COLLABORATOR`. Please note that these usernames cannot be the same as each other, and both of them must be real github usernames. The collaborator user does not need to be added as a collaborator to your test repo or organization, but as the acceptance tests do real things (and will trigger some notifications for this user), you should probably make sure the person you specify knows that you're doing this just to be nice. You can also export `GITHUB_TEST_COLLABORATOR_TOKEN` in order to test the invitation acceptance.

Additionally the user exported as `GITHUB_TEST_USER` should have a public email address configured in their profile; this should be exported as `GITHUB_TEST_USER_EMAIL` and the Github name exported as `GITHUB_TEST_USER_NAME` (this could be different to your GitHub login).

Finally, export the ID of the release created in the template repository as `GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID`

## Resources

- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
- [GitHub Help](https://help.github.com)
114 changes: 14 additions & 100 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,31 @@
Terraform Provider
==================
Terraform Provider GitHub
=========================

<img src="https://cloud.githubusercontent.com/assets/98681/24211275/c4ebd04e-0ee8-11e7-8606-061d656a42df.png" width="72" height="">

<img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" width="300px">

- Website: https://www.terraform.io
- [![Gitter chat](https://badges.gitter.im/hashicorp-terraform/Lobby.svg)](https://gitter.im/hashicorp-terraform/Lobby)
- Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool)

<img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" width="600px">

Requirements
------------
## Requirements

- [Terraform](https://www.terraform.io/downloads.html) 0.10.x
- [Go](https://golang.org/doc/install) 1.13 (to build the provider plugin)

Building The Provider
---------------------

Clone repository to: `$GOPATH/src/github.com/terraform-providers/terraform-provider-github`

```sh
$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
$ git clone [email protected]:terraform-providers/terraform-provider-github.git
```

Enter the provider directory and build the provider

```sh
$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-github
$ make build
# or if you're on a mac:
$ gnumake build
```

Using the provider
----------------------
## Usage

Detailed documentation for the GitHub provider can be found [here](https://www.terraform.io/docs/providers/github/index.html).

Developing the Provider
---------------------------

If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.11+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`.

To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.

```sh
$ make build
...
$ $GOPATH/bin/terraform-provider-github
...
```

In order to test the provider, you can simply run `make test`.

```sh
$ make test
```

In order to run the full suite of Acceptance tests, run `make testacc`.

*Note:* Acceptance tests create real resources, and often cost money to run.

```sh
$ make testacc
```

Acceptance test prerequisites
-----------------------------
In order to successfully run the full suite of acceptance tests, you will need to have the following:

export `https://api.github.com/` as the environment variable `GITHUB_BASE_URL`.

### GitHub personal access token
You will need to create a [personal access token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) for
testing. It will need to have the following scopes selected:
* repo
* admin:org
* admin:public_key
* admin:repo_hook
* admin:org_hook
* user
* delete_repo
* admin:gpg_key

Once the token has been created, it must be exported in your environment as `GITHUB_TOKEN`.

### GitHub organization
If you do not have an organization already that you are comfortable running tests against, you will need to [create one](https://help.github.com/en/articles/creating-a-new-organization-from-scratch). The free "Team for Open Source" org type is fine for these tests. The name of the
organization must then be exported in your environment as `GITHUB_OWNER`. If you are interested in using and/or testing Github's [Team synchronization](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/synchronizing-teams-between-your-identity-provider-and-github) feature, you will need to have an organization that uses Github Enterprise Cloud in addition to the requirements defined in the Github docs and set the environment variable `ENTERPRISE_ACCOUNT` to `true`.

### Test repositories
In the organization you are using above, create the following test repositories:
## Contributing

* `test-repo`
* The description should be `Test description, used in GitHub Terraform provider acceptance test.`
* The website url should be `http://www.example.com`
* Create two topics within the repo named `test-topic` and `second-test-topic`
* In the repo settings, make sure all features and merge button options are enabled.
* Create a `test-branch` branch
* `test-repo-template`
* Configure the repository to be a [Template repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)
* Create a release on the repository with `tag = v1.0`
Detailed documentation for contributing to the GitHub provider can be found [here](CONTRIBUTING.md).

Export an environment variable corresponding to `GITHUB_TEMPLATE_REPOSITORY=test-repo-template`.
## Roadmap

### GitHub users
Export your github username (the one you used to create the personal access token above) as `GITHUB_TEST_USER`. You will need to export a
different github username as `GITHUB_TEST_COLLABORATOR`. Please note that these usernames cannot be the same as each other, and both of them
must be real github usernames. The collaborator user does not need to be added as a collaborator to your test repo or organization, but as
the acceptance tests do real things (and will trigger some notifications for this user), you should probably make sure the person you specify
knows that you're doing this just to be nice. You can also export `GITHUB_TEST_COLLABORATOR_TOKEN` in order to test the invitation acceptance.
This project leverages [Milestones](https://github.com/terraform-providers/terraform-provider-github/milestones) to scope upcoming features and bug fixes. Issues that receive the most recent discussion or the most reactions will be more likely to be included in an upcoming release.

Additionally the user exported as `GITHUB_TEST_USER` should have a public email address configured in their profile; this should be exported
as `GITHUB_TEST_USER_EMAIL` and the Github name exported as `GITHUB_TEST_USER_NAME` (this could be different to your GitHub login).
## Support

Finally, export the ID of the release created in the template repository as `GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID`
This is a community-supported project. GitHub Support is not responsible for maintenance. Please engage with the community via Issues for support.
3 changes: 3 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)

Thanks for helping make this project safe for everyone.