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.
The purpose of dwylbot
will remain unclear
if you have not read the following:
Please read them and come back!
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 theawaiting-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 | remove "awaiting-review" and replace with "merge-conflicts". @username assigned. | |
"awaiting-review" with no assignees or reviewers | - | ||
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 | - | |
"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 | 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!
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!
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.
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.
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 GitHub repo to your personal computer:
git clone git@github.com:dwyl/dwylbot.git && cd dwylbot
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. 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.
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 thesource
command.
mix deps.get && npm install
Run the tests:
mix test
mix ecto.create && mix ecto.migrate
mix phoenix.server
You should see:
[info] Running Dwylbot.Endpoint with Cowboy using http://localhost:4000
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...?
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
Need an example GitHub Webhook request payload for this... see: dwyl#6 (comment)
See: https://developer.github.com/webhooks/creating/
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:"
- 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"... - 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. - 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
.