krosti / dwylbot

:robot: Automating our GitHub Workflow to improve team communication/collaboration and reduce tedious repetition!

dwylbot

"GitHub Workflow Automation, Helpful Hints & Timely Tips"

Automating our GitHub workflow to .reduce the number of clicks the people need to perform
to get their work done and help everyone communicate better with team members.

Prerequisite to Understanding dwylbot

The purpose of dwylbot will remain unclear if you have not read the following:

• github.com/dwyl/github-reference
• github.com/dwyl/contributing

Please read them and come back!

Why?

dwyl's Workflow is a carefully crafted sequence of steps designed to ensure everyone in the team can communicate and see the status of work.

Learning the Workflow is never instantaneous. At the start of a project the more experienced people in the team end up having to do a bit of "workflow mentoring". e.g:

"You missed a step in the workflow which means the team is unaware of state/progress on this feature..."
"Please remember to refer to the GitHub issue in your commit messages so it is clear what each commit is for."
"Please apply the awaiting-review label when you want someone to review your work..."
"Please only assign a Pull Request for review once all the tests have passed on CI..."

We've devised a set of rules and actions to respond to these problems, they look like this:

Category	Rule	dwylbot comments	Labels changed
Pull Requests	"awaiting-review" and a merge conflict, #64	⚠️ @username, the pull request has a merge conflict., Please resolve the conflict and reassign when ready 👍, Thanks!	remove "awaiting-review" and replace with "merge-conflicts". @username assigned.
	"awaiting-review" with no assignees or reviewers	⚠️ @username, the pull request is in "awaiting-review" but doesn't have a reviewer or correct assignee. Please assign someone to review the pull request, thanks.	-
	Must have a description, #98	🛑 @#{login}, the pull request has no description!, Please add more details to help us understand the context of the pull request, Please read our Contribution guide on how to create a good pull request, Thanks! ❤️	-
	If a PR has a reviewer, must have "awaiting-review" label and reviewer as assignee	👋 @#{login}, you have requested a review for this pull request so we have taken the liberty of assigning the reviewers 🎉. Have a great day ☀️ and keep up the good work 💻 👏	reviewer added as assignee, "awaiting-review" label added.
Issues	Must have a description, #76	⚠️ @username, this issue has no description. Please add a description to help others understand the context of this issue.	-
	"in-progress" label with no assignee, #7	@username the in-progress label has been added to this issue without an Assignee. dwylbot has automatically assigned you.	@username assigned to issue.
	"in progress" label with assignee removed, #71	⚠️ @username the assignee for this issue has been removed with the in-progress label still attached. Please remove the in-progress label if this issue is no longer being worked on or assign a user to this issue if it is still in progress.	-
	"in-progress" label with no time estimate, #61	@username the in-progress label has been added to this issue without a time estimation. Please add a time estimation to this issue before applying the in-progress label.	-

For a list of rules we're still implementing check out: dwyl#5

dwylbot automates giving "workflow related feedback" which saves everyone time!

What?

We use GitHub as our "single source of truth" (one place to keep all our information so we don't lose anything important!).
We also use GitHub to discuss questions/ideas/features/improvements, estimate the effort required to implement an idea (or "fix" an existing feature that is not working as expected) and then to track the progress while the work is being done and record how much time a person spent on the task/feature.
We refer to this as our "workflow".

dwylbot helps the humans learn & follow the workflow so we communicate better and get more done!

Install

To install and manage dwylbot on your repositories:

• visit the dwylbot home page or you can directly access the dwylbot installation page: https://github.com/apps/dwylbot

• click on "Manage dwylbot installations". This will open the dwylbot github app page.

• click configure to select the organisations where you want dwylbot to operate

• you can install dwylbot on all the repositories of the organisation or you can select specific repositories

• click install. dwylbot is now installed 🎉 Just use Github as normal and dwylbot will help enhance your team's workflow.

How?

This project is written in Elixir and uses a Phoenix web server tested by Travis and running on Heroku.
If you are new to any of these tools/technologies you won't understand some of the code in this repo, so, please read/learn:

• Elixir: https://github.com/dwyl/learn-elixir
• Phoenix: https://github.com/dwyl/learn-phoenix-framework
• Travis https://github.com/dwyl/learn-travis
• Heroku: https://github.com/dwyl/heroku

Note: you don't need to be an "expert" in any of these things to start understanding the project, but it helps to know the basics.

Run The Project Locally!

The "production" version of dwylbot runs on Heroku, but we develop it locally and you can easily run it on your computer.

Note: only try to run this on your computer once you've understood Elixir & Phoenix.

Clone the Repository

Clone the GitHub repo to your personal computer:

git clone [e-mail]:dwyl/dwylbot.git && cd dwylbot

Create a GitHub Application

If you don't already have a GitHub application with valid keys you can use to run this project on your localhost, please follow these instructions: https://developer.github.com/apps

Install ngrok

Install ngrok. If you have homebrew, you can do this by running brew install ngrok

Then in your terminal enter ngrok http 4000 to generate an SSH between your localhost:4000 and ngrok.io. Copy the http ngrok URL that appears in your terminal. Paste this URL into the webhook URL input of your GitHub app settings followed by '/event/new'. Update your other GitHub app settings as follows:

(Replace 'naaz-dwylbot' with your own GitHub app name)

NOTE: you will need to uodate the webhook URL everytime you disconnect/connect to ngrok because a different URL is generated everytime.

Define Local Environment Variables

If you are new to "Environment Variables", please read: github.com/dwyl/learn-environment-variables

To run the application on your localhost (personal computer) create an .env file where you can define your environment variables.

dwylbot/.env:

export GITHUB_CLIENT_ID=FollowTheInstructionsToCreateAnAppOnGitHub
export GITHUB_CLIENT_SECRET=*******
export DATABASE_URL=****
# SECRET_KEY_BASE is required for Auth Cookie:
export SECRET_KEY_BASE=MustBeA64ByteStringProbablyBestToGenerateUsingCryptoOrJustUseThisWithSomeRandomDigitsOnTheEnd1234567890

Then execute the command source .env which will create your environment variables

Note: This method only adds the environment variables locally and temporarily
so you need to start your server in the same terminal where you ran the source command.

Install Dependencies

mix deps.get && npm install

Confirm Everything is working

Run the tests:

mix test

Creat the Database (if it does not already exist)

mix ecto.create && mix ecto.migrate

Run the Server

mix phoenix.server

You should see:

[info] Running Dwylbot.Endpoint with Cowboy using http://localhost:4000

View the Project in your Web Browser

Open http://localhost:4000 in your web browser.

Ok, so you know the Phoenix server is working. That's nice, but what does it actually do...?

Understanding The Project

Routing

Given your Phoenix knowledge, you know that the first place to look when you want to understand
a Phoenix project is: web/router.ex

In this case we only have one (interesting) route: /event/new

Tests!

Make a cURL Request to the POST /event/new

Need an example GitHub Webhook request payload for this... see: dwyl#6 (comment)

See: https://developer.github.com/webhooks/creating/

tl;dr

on the team no one knows exactly what is going on at all times without having to ask.

With our GitHub-based Workflow, we successfully avoid the need for "project status update meetings":

For anyone who has never worked in a "really big" company where people have meetings about having meetings and it can feel like "there are too many steps to get work done...".
To those people we say: "you have three options:"

1. Get a job at a "Fortune 500 Company" (that has been around for 30+ years and claims to be "agile")
   .then come back chat about getting work done in teams; we will give you a shoulder to cry on!
   We promise not to say "I told you so" when you tell us we were "so right"...
2. Get a job in a small company (fewer than 10 people all co-located in the same office) where no "process" is required because they "just get stuff done!" Stay with that company long enough to feel the "growing pains" of not having a clearly defined workflow.
   .then try to retrospectively apply a workflow and teach your colleagues how to cooperate effectively.
3. Trust those of us who have felt the pain of working in (multiple) horribly complex companies and have crafted a workflow that ensures the highest level of team communication/productivity.

Organizations regularly approach us to teach dwyl's workflow to their team(s). We have done many workshops to that end.
Sadly, delivering in-person training does not scale. So we decided to automate our workflow with dwylbot.