Skip to content

Commit 41b240e

Browse files
author
Jeremy Udit
authored
Update Documentation Ahead Of Project Transfer (integrations#587)
- Adds CONTRIBUTING.md - Adds SECURITY.md - Adds CONTRIBUTING.md - Minimizes README.md
1 parent 26f977c commit 41b240e

File tree

4 files changed

+240
-100
lines changed

4 files changed

+240
-100
lines changed

‎CODE_OF_CONDUCT.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to make participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, sex characteristics, gender identity and expression,
9+
level of experience, education, socio-economic status, nationality, personal
10+
appearance, race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies within all project spaces, and it also applies when
49+
an individual is representing the project or its community in public spaces.
50+
Examples of representing a project or community include using an official
51+
project e-mail address, posting via an official social media account, or acting
52+
as an appointed representative at an online or offline event. Representation of
53+
a project may be further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72+
73+
[homepage]: https://www.contributor-covenant.org
74+
75+
For answers to common questions about this code of conduct, see
76+
https://www.contributor-covenant.org/faq

‎CONTRIBUTING.md

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
## Contributing
2+
3+
Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
4+
5+
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).
6+
7+
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.
8+
9+
## Submitting a pull request
10+
11+
0. Fork and clone the repository
12+
0. Create a new branch: `git checkout -b my-branch-name`
13+
0. Make your change, add tests, and make sure the tests still pass
14+
0. Push to your fork and submit a pull request
15+
0. Pat your self on the back and wait for your pull request to be reviewed and merged.
16+
17+
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
18+
19+
- Discuss your changes with the community in an issue.
20+
- Allow your pull request to receive edits by maintainers.
21+
- Write tests.
22+
- 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.
23+
- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
24+
25+
## Automated And Manual Testing
26+
27+
### Overview
28+
29+
When raising a pull request against this project, automated tests will be launched to run our test suite.
30+
31+
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.
32+
33+
34+
### Building The Provider
35+
36+
Clone the provider
37+
```sh
38+
$ git clone [email protected]:terraform-providers/terraform-provider-github.git
39+
```
40+
41+
Enter the provider directory and build the provider
42+
43+
```sh
44+
$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-github
45+
$ make build
46+
# or if you're on a mac:
47+
$ gnumake build
48+
```
49+
50+
### Developing The Provider
51+
52+
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`.
53+
54+
To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
55+
56+
```sh
57+
$ make build
58+
...
59+
$ $GOPATH/bin/terraform-provider-github
60+
...
61+
```
62+
63+
In order to test the provider, you can simply run `make test`.
64+
65+
```sh
66+
$ make test
67+
```
68+
69+
In order to run the full suite of Acceptance tests, run `make testacc`.
70+
71+
*Note:* Acceptance tests create real resources, and often cost money to run.
72+
73+
```sh
74+
# run all tests through `make`
75+
$ make testacc
76+
# run all tests directly
77+
$ go test -v ./...
78+
# run specific test
79+
$ go test -v ./... -run TestAccProviderConfigure
80+
```
81+
82+
Commonly required environment variables are listed below:
83+
84+
```console
85+
export TF_LOG=DEBUG
86+
export GITHUB_ORGANIZATION=
87+
export GITHUB_BASE_URL=
88+
export GITHUB_OWNER=
89+
export GITHUB_TEST_OWNER=
90+
export GITHUB_TEST_ORGANIZATION=
91+
export GITHUB_TEST_USER_TOKEN=
92+
```
93+
94+
See [this project](https://github.com/terraformtesting/acceptance-tests) for more information on how tests are run automatically.
95+
96+
### GitHub Personal Access Token
97+
98+
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
99+
testing. It will need to have the following scopes selected:
100+
* repo
101+
* admin:org
102+
* admin:public_key
103+
* admin:repo_hook
104+
* admin:org_hook
105+
* user
106+
* delete_repo
107+
* admin:gpg_key
108+
109+
Once the token has been created, it must be exported in your environment as `GITHUB_TOKEN`.
110+
111+
### GitHub Organization
112+
113+
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`.
114+
115+
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.
116+
117+
### Test Repositories
118+
119+
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:
120+
121+
In the organization you are using above, create the following test repositories:
122+
123+
* `test-repo`
124+
* The description should be `Test description, used in GitHub Terraform provider acceptance test.`
125+
* The website url should be `http://www.example.com`
126+
* Create two topics within the repo named `test-topic` and `second-test-topic`
127+
* In the repo settings, make sure all features and merge button options are enabled.
128+
* Create a `test-branch` branch
129+
* `test-repo-template`
130+
* Configure the repository to be a [Template repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)
131+
* Create a release on the repository with `tag = v1.0`
132+
133+
Export an environment variable corresponding to `GITHUB_TEMPLATE_REPOSITORY=test-repo-template`.
134+
135+
### GitHub Users
136+
137+
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.
138+
139+
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).
140+
141+
Finally, export the ID of the release created in the template repository as `GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID`
142+
143+
## Resources
144+
145+
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
146+
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
147+
- [GitHub Help](https://help.github.com)

‎README.md

+14-100
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,31 @@
1-
Terraform Provider
2-
==================
1+
Terraform Provider GitHub
2+
=========================
3+
4+
<img src="https://cloud.githubusercontent.com/assets/98681/24211275/c4ebd04e-0ee8-11e7-8606-061d656a42df.png" width="72" height="">
5+
6+
<img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" width="300px">
37

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

8-
<img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" width="600px">
9-
10-
Requirements
11-
------------
12+
## Requirements
1213

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

16-
Building The Provider
17-
---------------------
18-
19-
Clone repository to: `$GOPATH/src/github.com/terraform-providers/terraform-provider-github`
20-
21-
```sh
22-
$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
23-
$ git clone [email protected]:terraform-providers/terraform-provider-github.git
24-
```
25-
26-
Enter the provider directory and build the provider
27-
28-
```sh
29-
$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-github
30-
$ make build
31-
# or if you're on a mac:
32-
$ gnumake build
33-
```
34-
35-
Using the provider
36-
----------------------
17+
## Usage
3718

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

40-
Developing the Provider
41-
---------------------------
42-
43-
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`.
44-
45-
To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
46-
47-
```sh
48-
$ make build
49-
...
50-
$ $GOPATH/bin/terraform-provider-github
51-
...
52-
```
53-
54-
In order to test the provider, you can simply run `make test`.
55-
56-
```sh
57-
$ make test
58-
```
59-
60-
In order to run the full suite of Acceptance tests, run `make testacc`.
61-
62-
*Note:* Acceptance tests create real resources, and often cost money to run.
63-
64-
```sh
65-
$ make testacc
66-
```
67-
68-
Acceptance test prerequisites
69-
-----------------------------
70-
In order to successfully run the full suite of acceptance tests, you will need to have the following:
71-
72-
export `https://api.github.com/` as the environment variable `GITHUB_BASE_URL`.
73-
74-
### GitHub personal access token
75-
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
76-
testing. It will need to have the following scopes selected:
77-
* repo
78-
* admin:org
79-
* admin:public_key
80-
* admin:repo_hook
81-
* admin:org_hook
82-
* user
83-
* delete_repo
84-
* admin:gpg_key
85-
86-
Once the token has been created, it must be exported in your environment as `GITHUB_TOKEN`.
87-
88-
### GitHub organization
89-
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
90-
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`.
91-
92-
### Test repositories
93-
In the organization you are using above, create the following test repositories:
21+
## Contributing
9422

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

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

107-
### GitHub users
108-
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
109-
different github username as `GITHUB_TEST_COLLABORATOR`. Please note that these usernames cannot be the same as each other, and both of them
110-
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
111-
the acceptance tests do real things (and will trigger some notifications for this user), you should probably make sure the person you specify
112-
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.
27+
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.
11328

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

117-
Finally, export the ID of the release created in the template repository as `GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID`
31+
This is a community-supported project. GitHub Support is not responsible for maintenance. Please engage with the community via Issues for support.

‎SECURITY.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
2+
3+
Thanks for helping make this project safe for everyone.

0 commit comments

Comments
 (0)