Problem Child
Allows authenticated or anonymous users to fill out a standard web form to create GitHub issues.
How it works
- You create a standard HTML form, defining what fields you'd like a given authenticated or anonymous user to fill out
- They go to a hosted URL and fill out the form
- The fields are converted to markdown bullets and inserted into the body of a new issue created against the GitHub repo you specify
Usage
- Create a
Gemfile
and addgem "problem_child"
- Create a
config.ru
file and add the following:
require "problem_child"
run ProblemChild::App
Then, follow the configuration options below.
Requirements
If you have OAuth (e.g., non-anonymous submission), you'll need to have Redis running to properly maintain sessions and support submissions larger than 4k:
On OS X, run brew install redis
to install, followed by redis-server
to run the redis server. The site should work fine, but for tests to pass, you'll want to add REDIS_URL=redis://localhost:6379
to your .env
file.
On Heroku you'll want to run heroku addons:create heroku-redis:hobby-dev
to add a free Redis instance to your app (Heroku will set REDIS_URL
for you).
Configuring
First, you must set the following environmental variable:
GITHUB_REPO
- the repo to open the issue against in the form ofowner/repo
You must also set one of the following:
GITHUB_TOKEN
- A personal access token for a bot account with the ability to create an issue in theGITHUB_REPO
if you would like all submissions to be anonymousGITHUB_ORG_ID
- The GitHub Org ID e.g,@whitehouse
if you'd like all users to authenticate against a GitHub Org prior to being presented the form, orGITHUB_TEAM_ID
- The numeric Team ID (e.g., 1234) if you'd like all users to authenticate against a GitHub Team prior to being presented the form
If you are using OAuth Authentication (e.g., you set GITHUB_ORG_ID
or GITHUB_TEAM_ID
so that the user submits as themselves), you must also set the following as environmental variables:
GITHUB_CLIENT_ID
andGITHUB_CLIENT_SECRET
- Created via github.com/settings/applications/new
Pro-tip: When developing locally, you can add these values to a .env
file in the project root, and they will be automatically read in on load
Customizing
By default, Problem Child will prompt the user with a simple form that contains only the title and body. If you'd like to customize the form, you must do the following:
- Create a new directory called
views
- Create a
layout.erb
andform.erb
- Customize both the layout and form as a standard HTML form. Check out these examples to get started.
- Add the following (middle) line to your
config.ru
file:
require "problem_child"
ProblemChild.views_dir = "/path/to/your/views/directory"
run ProblemChild::App
Pro-tip: You can use any standard HTML form fields, but be sure to name one field title
, which will become the issue title.
Pro-tip II: Problem child can set labels. You can do this either as a hidden field:
<input type="hidden" name="labels[]" value="bug" />
or as a checkbox:
<input type="checkbox" name="labels[]" value="bug" />
<input type="checkbox" name="labels[]" value="suggestion" />
Pro-tip III: Set the public directory
By default Problem child points to an internal public directory which includes jQuery and Twitter Bootstrap. You can add them to your custom layout.erb:
<link href="/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="/vender/jquery/dist/jquery.min.js"></script>
However, if you would like to add more files to your form app (e.g., favicon, custom CSS & JS files, etc.), you can redefine where the public directory points:
require "problem_child"
ProblemChild.views_dir = "/path/to/your/views/directory"
ProblemChild.public_dir = Rails.public_path
run ProblemChild::App
Note that you will lose access to the bundled jQuery & Bootstrap libraries and will have to put copies into your new public directory to use them.
Creating pull requests
Problem child can also be used to create pull requests. Simply add one or more file inputs to your form. The uploaded files will be committed to a newly created feature branch, and a pull request will be created against the repo's primary branch with the rest of the form content. You'll also want to change the form type to enctype="multipart/form-data"
.
<form method="post" enctype="multipart/form-data">
<input type="file" name="file" />
<input type="submit" />
</form>
Contributing
- Fork it ( https://github.com/[my-github-username]/problem_child/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request