first-timers-only issue bot

[gr2m]

🎯⛳ The goal

We want to streamline the process to create very simple contributor-friendly issues to help onboard more people to become Open Source contributors. See issues with first-timers-only label for examples.

The goal is to make creating a first-timers-only issue as simple as making the fix ourselves.

Note that this is not a an issue releated to a single bug or feature, but a project. We will use this issue to discuss the overall idea and progress.

🐶 ❓ The Motivation

At Hoodie, we aim to become the most welcoming Open Source community possible. We joined forces with initiatives like First Timers Only and Your First PR to actively reach out to new contributors and create an environment where they feel encouraged and supported.

Creating what we call starter issues is one aspect of that. And it is one of the most successful. A subset of these starter issues are super simple fixes like typos, so they are perfect to onboard people and help them get familiar with GitHub and the pull request workflow. Because typos and similar issues are so trivial, we should basically be able to automatically generate the entire starter issue based on a diff.

💡💥 How things could work

Say I’m a Hoodie contributor and find a typo somewhere. Instead of fixing the issue directly in the master branch or creating a pull request, I create a new branch that is call something like first-timers-only-typo-in-title. GitHub will notify the "first-timers-only issue bot" about the new branch using webhooks. The boot will see that the new branch is starting with first-timers-only and will create a new issue at https://github.com/hoodiehq/camp/issues/new based on a template and assign the first-timers-only and the up-for-grabs label.

If the commit body can be used to add some context information. If left empty, the 🤔 What you will need to know section of the issue will simply say "Nothing :)". Otherwise the commit body will be used there.

👩‍🏫🙋‍♂️ What you will need to know

The bot will be an Open Source Node.js service, built with our server framework of choice hapi and deployed to now.

It will use GitHub’s API and webhooks.

📋 Step by Step

• 🙋 Claim this issue: @agonzalez0515 & @Techforchange , supported by @gr2m

• 👌 Accept our invitation to this repository. Once accepted, assign yourself to this repository

• 👓 Please review our Code of Conduct
  In a nutshell: be patient and actively kind with us 😊

• Create hoodiehq/first-timers-only-bot repository

  • create a README based on the content in this issue

• Version 1: "copy & paste"
  On the "/" landing page, show a text input to enter a URL to a branch on GitHub. When submitted, the server will respond with a link to the changed file, line number(s) and the diff as well as the Markdown that we can directly copy & paste into https://github.com/hoodiehq/camp/issues/new

  • Create a hapijs app with a public/ folder which contents get served at "/" (see inert)

  • Create public/index.html with a form to submit the branch URL. Feel free to add CSS/JS or external libraries like jQuery.

  • Define a POST /starter-issue route which takes the URL from the submitted form and responds with JSON like {"ok":true}

  • Make the form from public/index.html send background request when submitting the form. Show the response, e.g. with an alert

  • in the POST /starter-issue handler, load the meta information about that branch using GitHub’s API (see Get branch). The response will give you the sha for the commit. You can use that to get the commit meta information (GET repo commit, see example response). The response includes a "files" array which will have one entry with all information we need

  • Instead of responding with {"ok":true}, respond with path to the changed file, the diff, commit message and commit body. Based on the new response, show a textarea with markdown that can be copy & pasted into a new issue. You can use markdown.js to also render a preview of it. The result could look something like this

    Update the file [CONTRIBUTING.md](https://github.com/hoodiehq/hoodie/blob/master/CONTRIBUTING.md)
    in the `hoodie` repository (press the little pen Icon) and edit the line 220 as shown below
    
    ```diff
    @@ -220,7 +220,7 @@ If you have commit access, please follow this process for merging patches and cu
        1. If there is a breaking change, make sure that `BREAKING CHANGE:` with
        _exactly_ that spelling (incl. the \":\") is in body of the according
        commit message. This is _very important_, better look twice :)
    -   2. Make sure there are `fix: ...` or `feat: ...` commits depending on wether
    +   2. Make sure there are `fix: ...` or `feat: ...` commits depending on whether
        a bug was fixed or a feature was added. **Gotcha:** look for spaces before
        the prefixes of ` fix:` and ` feat:`, these get ignored by semantic-release.
        3. Use the \"Rebase and merge\" button to merge the pull request.
    ```
    

  • Now instead of only showing this one step, add the entire content of a first-timers-only issue. You can use this one as a template. Use the dynamic content from above for the "📝 Update ..." step

  • deploy the bot to now

  • test & fix all the things

  • celebrate 🎉

• Version 2: "on demand"
  Instead of needing to copy & paste the content for a new issue, create a new issue directly from the hapi app. After submitting the URL, show a link to the created issue so it can be reviewed and edited if needed. Use a token by @LowProfileDog for authentication

• Version 3: "the magic bot"
  Setup a webhook to notify our service about changes. You can use ngrok so that GitHub can reach your local server, or create an app on glitch.com, which lets you host node.js application for free and we can all collaborate on it :) Filter out all events but new branches created that start with first-timers-only. For all new first-timers-only*, automagically create new starter issues as before ✨

• Version 4: probot 🤖❗️
  probot is a bot framework for GitHub – exactly what we need. Probot takes away a lot of generic implementation that you created manually and instead lets you use something like this to run code each time a branch was created

  module.exports = robot => {
    robot.on('push', (event, context) => {
      // run only for newly created branches that start with "first-timers-"
      if (event.ref_type === 'branch' && /^first-timers-/.test(event.ref)) {
        // create issue here
      }
    });
  };

• The last step is to setup a continuous deployment of the first-timers-only bot to now from travis whenever something gets merged into master

🤔❓ Questions

Ping us in the Hoodie Chat or on Twitter

[jeanhl]

Hey Gregor, Thanks for making the first-timer guide. I did my first pull-request last year as a first-timer and have been looking for issues easy enough for a beginner like me. :) I look forward to contributing more. Have a great weekend! Jean

…

On Sat, Feb 18, 2017 at 12:56 PM, Gregor Martynus ***@***.***> wrote: 🎯⛳ The goal We want to streamline the process to create very simple contributor-friendly issues to help onboard more people to become Open Source contributors. See issues with first-timers-only label <https://github.com/hoodiehq/camp/issues?utf8=%E2%9C%93&q=label%3Afirst-timers-only> for examples. The goal is to make creating a first-timers-only issue as simple as making the fix ourselves. Note that this is not a an issue releated to a single bug or feature, but a project. We will use this issue to discuss the overall idea and progress. 🐶 ❓ The Motivation At Hoodie, we aim to become the most welcoming Open Source community <http://hood.ie/blog/welcoming-communities.html> possible. We joined forces with initiatives like First Timers Only <http://www.firsttimersonly.com/> and Your First PR <http://yourfirstpr.github.io/> to actively reach out to new contributors and create an environment where they feel encouraged and supported. Creating what we call starter issues <http://hood.ie/blog/starter-issues.html> is one aspect of that. And it is one of the most successful. A subset of these starter issues are super simple fixes like typos, so they are perfect to onboard people and help them get familiar with GitHub and the pull request workflow. Because typos and similar issues are so trivial, we should basically be able to automatically generate the entire starter issue based on a diff. 💡💥 How things could work Say I’m a Hoodie contributor and find a typo somewhere. Instead of fixing the issue directly in the master branch or creating a pull request, I create a new branch that is call something like first-timers-only-typo-in- title. GitHub will notify the "first-timers-only issue bot" about the new branch using webhooks. The boot will see that the new branch is starting with first-timers-only and will create a new issue at https://github.com/hoodiehq/camp/issues/new based on a template and assign the first-timers-only and the up-for-grabs label. If the commit body can be used to add some context information. If left empty, the 🤔 What you will need to know section of the issue will simply say "Nothing :)". Otherwise the commit body will be used there. 👩‍🏫🙋‍♂️ What you will need to know The bot will be an Open Source Node.js <https://nodejs.org/en/> service, built with our server framework of choice hapi <https://hapijs.com/> and deployed to now <https://zeit.co/now>. It will use GitHub’s API <https://developer.github.com/v3/> and webhooks <https://developer.github.com/webhooks/>. 📋 Step by Step - 🙋 *Claim this issue*: @jsoranno <https://github.com/jsoranno>, supported by @gr2m <https://github.com/gr2m> - 👌 *Accept our invitation* to this repository. Once accepted, assign yourself to this repository - 👓 *Please review* our Code of Conduct <http://hood.ie/code-of-conduct/> In a nutshell: be patient and actively kind with us 😊 - Create hoodiehq/first-timers-only-issue-bot <https://github.com/hoodiehq/first-timers-only-issue-bot> repository - create a README based on the content in this issue - Version 1: "copy & paste" On the "/" landing page, show a text input to enter a URL to a branch on GitHub. When submitted, the server will respond with a link to the changed file, line number(s) and the diff as well as the Markdown that we can directly copy & paste into https://github.com/hoodiehq/ camp/issues/new - Create a hapijs app with a public/ folder which contents get served at "/" (see inert <https://www.npmjs.com/package/inert>) - Create public/index.html with a form to submit the branch URL. Feel free to add CSS/JS or external libraries like jQuery. - Define a POST /starter-issue route which takes the URL from the submitted form and responds with JSON like {"ok":true} - Make the form from public/index.html send background request when submitting the form. Show the response, e.g. with an alert - in the POST /starter-issue handler, load the meta information about that branch using GitHub’s API (see Get branch <https://developer.github.com/v3/repos/branches/#get-branch>). The response will give you the sha for the commit. You can use that to get the commit meta information (GET repo commit <https://developer.github.com/v3/repos/commits/#get-a-single-commit>, see example response <https://api.github.com/repos/hoodiehq/hoodie/commits/b2f16b>). The response includes a "files" array which will have one entry with all information we need - Instead of responding with {"ok":true}, respond with path to the changed file, the diff, commit message and commit body. Based on the new response, show a textarea with markdown that can be copy & pasted into a new issue. You can use markdown.js <https://github.com/evilstreak/markdown-js> to also render a preview of it. - deploy the bot to now <https://zeit.co/now> - test & fix all the things - celebrate :party: - Version 2: "on demand" Instead of needing to copy & paste the content for a new issue, create a new issue directly from the hapi app. After submitting the URL, show a link to the created issue so it can be reviewed and edited if needed. Use a token by @LowProfileDog <https://github.com/lowprofiledog> for authentication - Version 3: "the magic bot" Setup a webhook <https://github.com/organizations/hoodiehq/settings/hooks/new> to notify our service about changes. Filter out all events but new branches created that start with first-timers-only. For all new first-timers-only*, automagically create new starter issues as before ✨ 🤔❓ Questions Ping us in the Hoodie Chat <http://hood.ie/chat/> or on Twitter <https://twitter.com/hoodiehq/> — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#105>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ATZqPrYgdJPXfewu_tAX-hFMYYmoCBLcks5rd1r9gaJpZM4MFQQn> .

[sohini-roy]

I would like to claim this issue!

[gr2m]

@sohini-roy I’m sorry but it’s already taken :)

[sohini-roy]

Hey , sorry i didn't know that . I have almost completed version 1 i.e. 7/8 of the given tasks of version 1. So i was wondering to send a pull request :)

[gr2m]

ooops :) If you like start a pull request and I can give you feedback on it, but then it’d be better to find something else to work on :)

[sohini-roy]

Thank you :)

I have started a pull request. Hope that's ok?

[gr2m]

@jsoranno any progress on this? Anything we can help with?

[jsoranno]

@gr2m Hi Gregor! I'm sorry it's taking me so long to get started. Wrapping up my job to start a new one is taking more than I expected. It looks like @sohini-roy would be a great person to take it over. I'd love to contribute once I get more comfortable at my new job. Thanks for being so supportive!!!!

[gr2m]

Okay :) Let me know when you are looking for something to work on. All the best for your new job :)

@sohini-roy @jeanhl I’d like to give this someone else to work on whom I promised a little project for a while now. If you two are still looking for something to contribute, I’d be happy to find something else? I think @sohini-roy is already busy working on the deployment documentation for linux right now :)

[jeanhl]

Absolutely. :)

…

On Sat, Mar 4, 2017 at 9:44 AM, Gregor Martynus ***@***.***> wrote: Okay :) Let me know when you are looking for something to work on. All the best for your new job :) @sohini-roy <https://github.com/sohini-roy> @jeanhl <https://github.com/jeanhl> I’d like to give this someone else to work on whom I promised a little project for a while now. If you two are still looking for something to contribute, I’d be happy to find something else? I think @sohini-roy <https://github.com/sohini-roy> is already busy working on the deployment documentation for linux right now :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#105 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ATZqPt0CWJ1sMh9nBlj94nke-hRmjYYJks5riaL7gaJpZM4MFQQn> .

[gr2m]

@jeanhl I’ve pinged you in slack :)

[sohini-roy]

Thank you @jeanhl for recommending me :)
I am towards the end of documentation @gr2m .I would love to work on a new issue :)

[harpreetsaini19]

I would like to claim this issue!

[gr2m]

Harpreet, have you actually read the issue? :) it’s been worked on for a long time now, you are a little too late I’m afraid

[gr2m]

The first timers app is ready and busy creating first-timers-only issues around GitHub https://github.com/apps/first-timers

Great work @agonzalez0515 & @Techforchange

[harpreetsaini19]

@gr2m Oh my bad, Sorry, but the issue was open and i just got confused by the available label which was added 2 days back. I would like to work on any open issue, can you suggest any?

[gr2m]

Oh you are right, I missed that. It was added by mistake, sorry for that :)