Creating a better way for developers to write in Github
Introduction
In this developer tutorial, we will build a contextual shortcut that will allow you to pre-fill the input textarea of any Github Issue or Pull Request page - using a template that follows the most common best practices.
Developers love Github but learning how to properly write issues and pull-requests is an art, and every company (or individual) has its own way to handle these two major developer activities.
Following best practices is advisable - since there are well-defined templates for writing either and they’re easy to learn but why not automate it - that way you don’t have to learn and remember it
Using this approach will make it easy how to structure them: for example when describing a bug, it’s best to be thorough and when creating a pull-request - it’s great to provide as much context and information as possible!
Although the objective of this tutorial is to write Issues or Pull Request - you can customize the code to handle any other type of writing, including Github wiki pages, comments etc. or maybe on a different git platform!
Let’s get started!
Finding the right bricks
In this tutorial we will be using the following bricks:
- Context Menu: to trigger the opening of the menu
- Show a modal or sidebar form: to accept user input
- Set Input Value: to set the selected template in the page’s textarea field with conditional operators
Assembling the bricks
Step 1. Configuring the Context Menu
First I will navigate to Github.com and open the PixieBrix editor
Let’s start by adding a brick called Context Menu - this means we’re triggering this mod by clicking an entry in the context menu of the browser (basically right-clicking)
- I am naming this Name:
Github Templates
- I am also naming the title of the mod
Github Templates
😂 - Leaving everything else default
It should look like this
Step 2. Opening a modal and letting user choose an option
We’re going to create a modal with a dropdown so the user can pick which template should be used.
To do this we’re going to add the Show a modal or sidebar form brick:
- We will name the variable for the selected value: template
- We’re setting the Form title field to
Github Templates
- We want to give a Label to the UI of this modal:
Template Type
- Let’s also add a field description:
Choose a template to use on this page
- Let’s make this modal be a dropdown so select input type as: dropdown
- Next we add three options to the dropdown:
- Pull Request
- Issue
- Blank
- Make the default option to be: Pull Request - by typing in the default option field
- Let’s also make this a required field by toggling the switch Required Field
- We want to be able to cancel this action, so toggle Cancelable on
- Finally let’s change the value of the Submit button to Generate
It should look like this
Step 3. Configuring the logic
In this step, we’re going the logic to automatically fill the form at the bottom of the “Issues” page on Github. For example this page here: https://github.com/pixiebrix/pixiebrix-extension/issues/new
To achieve this we’re going to add one brick called “Set Input Value”
We’re going to configure this brick like so:
First, we will press the blue button “Add Item”
We will add one item with the following:
Property name & Value:
selector: textarea
value:
#### What's this PR do?
#### Where should the reviewer start?
#### How should this be manually tested?
#### Any background context you want to provide?
#### What are the relevant tickets?
#### Screenshots (if appropriate)
#### What gif best describes this PR or how it makes you feel?
#### Definition of Done:
- Is there appropriate test coverage? (e.g. ChefSpec, Mocha/Chai, Python, etc.)
- Does this PR require a Selenium test? (e.g. Browser-specific bugs or complicated UI bugs)
- Does this PR require a regression test? All fixes require a regression test.
- Does this PR require a blog post? If so, ensure marketing has signed off on content.
- Does the [knowledge base](https://company.com) need to be updated?
- Does this add new dependencies? If so, does Chef, M4, or PIP requirements need to be updated?
- Will this feature require a new piece of infrastructure be implemented?
- Are any new services fully automated in Chef?
- Are there ChefSpec tests for the new Chef recipes/cookbooks?
- Does this PR require new Mixpanel or GA events?
- Is there appropriate logging included?
It should look like this
Now if you scroll down a little in the page editor we’re going to set the Advanced Options:
We will set Condition to be this string:
{{ true if @form.template == "Pull Request" }}
I will now add a second item to populate the title of this Github page - that is because
In this second item the property selector is: .input-lg
and the value is: Pull Request Template
What this does, is that it will return true - and hence allow the execution of this brick - ONLY if the chosen value from the dropdown @form.template equals “Pull Request”
Step 3.2
We’re going to copy and paste the same block we did above and tweak is slightly
To copy a brick select it and click the blue “Copy Brick” button, as shown in the image below:
Then, paste the copied brick below this brick by clicking the paste button.
This will allow for this brick to be copied and pasted below the 1st Set Input Value brick.
At this point, if you look on the left, you should have two “Set Input Value” bricks Let’s select the second one - the one we just pasted and modify its values like so:
Under inputs where the property is value, we will replace the content of the value box with
* **I'm submitting a ...**
- [ ] bug report
- [ ] feature request
- [ ] support request => Please do not submit support request here, see note at the top of this template.
- **Do you want to request a *feature* or report a *bug*?**
...
- **What is the current behavior?**
...
- **If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem**
...
- **What is the expected behavior?**
...
- **What is the motivation / use case for changing the behavior?**
...
- **Please tell us about your environment:**
- Version: 2.0.0-beta.X
- Browser: [all | Chrome XX | Firefox XX | IE XX | Safari XX | Mobile Chrome XX | Android X.X Web Browser | iOS XX Safari | iOS XX UIWebView | iOS XX WKWebView ]
- Language: [all | TypeScript X.X | ES6/7 | ES5 | Dart]
- **Other information** (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. stackoverflow, gitter, etc)
Under Advanced Options we will change the Condition to be:
{{ true if @form.template == "Issue" }}
Step 3.3
We’re going to copy and paste the same block we did above and tweak is slightly, again!!
Under inputs where the property is value, we will replace the content of the value box with Something else!
Under Advanced Options we will change the Condition to be:
{{ true if @form.template == "Other" }}
Step 4. Testing it all
At this point your page editor should look like this and you should have the following Bricks - note how we have 3 Set Input Value bricks:
To test this contextual shortcut, let’s navigate a Github repository, create a new issue. https://github.com/pixiebrix/pixiebrix-extension/issues/new
Then right-click anywhere on the page and let’s select the PixieBricks entry we just created.
Select one of the options and click Generate
If everything went well, you should see your chosen template appear in the textarea field on the page!
Where to go from here
You can change the number of templates by adding more fields to the modal and then adding the template in markdown - or any other text - directly in the third step.
If it’s not working you can try to do a couple of things:
- First, make sure you grant PixieBrix permission to view the page.
- Copy-paste the code for the bricks from this tutorial, it’s easy to make typos
- If you’re still stuck, post in the PixieBrix community and we will jump in to help you out!