From 0d249925935bb79054149836940b63bd37e61fcd Mon Sep 17 00:00:00 2001 From: Jeremy Udit Date: Wed, 4 Nov 2020 16:57:31 -0500 Subject: [PATCH] Update Documentation Ahead Of Project Transfer - Adds CONTRIBUTING.md - Adds SECURITY.md - Adds CONTRIBUTING.md - Minimizes README.md --- CODE_OF_CONDUCT.md | 76 +++++++++++++++++++++++ CONTRIBUTING.md | 147 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 114 +++++------------------------------ SECURITY.md | 3 + 4 files changed, 240 insertions(+), 100 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..3a64696bc2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -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 opensource@github.com. 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..78e2542a54 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 git@github.com: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) diff --git a/README.md b/README.md index 8f878827ff..b80ddf0429 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,31 @@ -Terraform Provider -================== +Terraform Provider GitHub +========================= + + + + - 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) - - -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 git@github.com: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. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000..798d64bce9 --- /dev/null +++ b/SECURITY.md @@ -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.