Merge pull request #49 from github/primetheus/oss-info

Adding OSS Info

.github/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+:wave: Hi there!
+We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
+
+## Submitting a pull request
+[Pull Requests][pulls] are used for adding new functionality, fixing bugs, improving documentation, and improving the developer experience overall.
+
+**With write access**
+1. Clone the repository (only if you do not have write access)
+1. Run `pipenv install`
+1. Create a new branch: `git checkout -b <username>/<my-branch-name>`
+1. Setup a [GitHub App][GitHub App] and follow the instructions in the [README][README]
+1. Configure your `.env` using the `.env.example` as a template
+1. Make your change
+1. Push and [submit a pull request][pr]
+1. Pat yourself on the back and wait for your pull request to be reviewed and merged.
+
+**Without write access**
+1. [Fork][fork] and clone the repository
+1. Run `pipenv install`
+1. Create a new branch: `git checkout -b <username>/<my-branch-name>`
+1. Setup a [GitHub App][GitHub App] and follow the instructions in the [README][README]
+1. Configure your `.env` using the `.env.example` as a template
+1. Make your change
+1. Push to your fork and [submit a pull request][pr]
+1. 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:
+
+- 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 [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+- Please honor the `<username>/<branch-name>` naming convention to help with sorting branches in the UI
+- **Test your changes**. Many users depend on this app's reliability. Please be sure to test your changes to make sure they do not break the functionality
+
+Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocking you.
+
+- Create a branch with a name that identifies the user and nature of the changes (similar to `<username>/<branch-purpose>`)
+- Open a pull request and request a review from a member of the appropriate `@github/ps-delivery` and/or `@github/ps-devops-engineering` teams
+
+## 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)
+
+[pulls]: https://github.com/github/saml-ldap-team-sync/pulls
+[pr]: https://github.com/github/saml-ldap-team-sync/compare
+[fork]: https://github.com/github/saml-ldap-team-sync/fork
+[README]: https://github.com/github/saml-ldap-team-sync#creating-the-github-app-on-your-github-instance
+[GitHub App]: https://github.com/settings/apps/new

README.md

@@ -14,16 +14,30 @@ This utility provides the following functionality:
 | LDAP SSL | No | SSL or TLS connections. This is a WIP |
 | Failure notifications | Yes | Presently supports opening a GitHub issue when sync failed. The repo is configurable. |
 | Sync on new team | Yes | Synchronize users when a new team is created |
-| Sync on team edit | No | This event is not processed currently, but can be easily added |
+| Sync on team edit | No | This event is not processed currently |
 | Custom team/group maps | Yes | The team `slug` and group name will be matched automatically, unless you define a custom mapping with `syncmap.yml` |
 | Dry run / Test mode | Yes | Run and print the differences, but make no changes |
 | Nested teams/groups | No | Synchronize groups within groups. Presently, if a group is a member of another group it is skipped |
 
-## Permissions and Events
-This application will need to be able to manage teams in GitHub,
-so the following `events` and `permissions` will be required.
-For more information on how to create a GitHub App, please visit
-https://developer.github.com/apps/building-github-apps/creating-a-github-app/
+## Creating the GitHub App on your GitHub instance
+1. On your GitHub instance, visit the `settings` page on the Organization that you want to own the **GitHub** App, and navigate to the `GitHub Apps` section.
+    - You can access this page by visiting the following url:
+      `https://<MY_GITHUB_HOSTNAME>/organizations/<MY_ORG_NAME>/settings/apps`
+2. Create a new **GitHub App** with the following settings:
+    - **Webhook URL**: URL of the machine on which this app has been deployed (Example: `http://ip.of.machine:3000`)
+    - **Homepage URL**: URL of the machine on which this app has been deployed (Example: `http://ip.of.machine:3000`)
+    - **Webhook Secret**: The webhook secret that will be or has been defined as an environment variable in your deployment environment as `WEBHOOK_SECRET`
+    - **Permissions and Events**: This application will need to be able to manage teams in GitHub, so the `events` and `permissions` listed below will be required. For more information on how to create a GitHub App, please visit https://developer.github.com/apps/building-github-apps/creating-a-github-app/
+3. Once these have been configured, select the `Create GitHub App` button at the bottom of the page to continue
+4. Make a note of the `APP ID` on your newly-created **GitHub App**. You will need to set this as an environment variable when you configure the app.
+5. Generate and download a private key from the new App page, and store it in your deployment environment. You can either do this by saving the file directly in the environment and specifying its path with the environment variable `PRIVATE_KEY_PATH`
+6. After you have created the **GitHub** App, you will need to install it to the desired **GitHub** Organizations.
+    - Select `Install App`
+    - Select `All Repositories` or the desired repositories you wish to watch
+
+### Permissions and Events
+
+#### Permissions
 
 | Category | Attribute | Permission |
 | --- | --- | --- |
@@ -32,6 +46,8 @@ https://developer.github.com/apps/building-github-apps/creating-a-github-app/
 | Repository permissions | `Issues` | `Read & write` |
 | Repostiroy permissions | `Metadata` | `Read-only` |
 
+#### Events
+
 | Event | Required? | Description |
 | --- | --- | --- |
 | `Team` | Optional | Trigger when a new team is `created`, `deleted`, `edited`, `renamed`, etc. |