Github makes a lovely workspace

[g105b]

I feel like Biff and I are bedded in nicely to Github's product offerings with the start of Trackshift, so I thought I'd write the first blog to discuss where the project is now and how we're fully utilising Github's features to open source our entire process, including the meetings we have and any business development that occurs.

It all starts at the pub

We made a point in not opening laptops during planning phases, because getting things down on physical pen and paper in a messy creative way doesn't tend to hinder the process of getting ideas out like computers do. That, plus a few pints of delicious ale, tends to put an interesting spin on our meetings.

The next day, we can reflect on our strange doodles and notes, and draft them up into a Discussion on Github. This is done using Markdown, the second best thing other than pen and paper to remove distractions when writing ideas down. I actually find it super useful to include a photograph of the original doodles, as I find it helps me crawl back into the mindspace that I was in at the time.

We typically break our meetings into technical and business, and get everything down into one Discussion page before continuing to break down the page into separate points.

It's then easy to expand upon certain points in the Discussion, converting important parts into Issues. Once this process is done, we have a numbered log of everything we've discussed, and there's nothing else we can think of doing that hasn't been allocated a number to refer to in the future.

Issues, Milestones and Releases

With all the issues in a single list, it's then easy to refer back to our original scribbles to categorise issues into larger milestones. A lot of issues will relate to each other very closely, so it makes sense to keep them together in a milestone for this purpose. In my opinion, milestones should be something that's achievable within a period of about two weeks (calendar based, not logged-time based). That way, you can generally have a good indication of the velocity of the project based on the current milestone's progress.

When an issue is worked on, a new branch will be created from the latest master version of the code. The branch name will include the issue number, so it's easy to know what it relates to, and we'll use commit messages to tag the issue when appropriate.

After an issue's code is completed, a pull request will be created, waiting for an in-person code review. Once the pull request is live, there's nothing stopping us working on other issues and then reviewing multiple PRs at once.

I think it's extremely beneficial to have in-person code reviews, where we can go through every line of code and question everything. Why did you do it this way? Why does the code look like that? Are you sure this should behave like this?

Code reviews don't need to take long, but they do need to engage all parties in order to be successful.

When a pull request is accepted and merged back to master, the master branch should automatically be released to a staging area on a server for testing. This way, there should be a continuously running test bed that we can always use for manual testing, or previewing upcoming features.

The live release period does not need to be up to date with master necessarily, and should be a more manual process. Github allow you to stage named Releases for this purpose - tagging a point in history with a version number. When a release is tagged, an automatic process should release to the live environment.

Actions

One of the newer features of Github is Actions, which can automate processes when something happens on the project. This is where the quality control happens.

As part of our meetings, we want to understand each feature perfectly well before deciding to start coding. We will use behaviour-driven-development language to keep our communication on-track wherever possible, and once we're both on the same page with what each feature should accomplish, we can translate this into Gherkin scripts to automate the testing of these business goals. We use Behat for this.

On top of the high level business goals, we need to test each individual unit of functionality on a technical level, which is where we use PHPUnit, the most commonly used unit test framework out there.

Finally, we utilise PHPStan to help catch potential bugs by analysing the quality of the code that's written.

All of these tests are an individual step in our Github Actions workflow file, and are all enforced before we are allowed to merge any pull requests.

You can see the project's workflow run statuses here (green ticks are good).

Wiki

From Wikipedia,

A wiki is an online hypertext publication collaboratively edited and managed by its own audience. A typical wiki contains multiple pages for the subjects or scope of the project, and could be either open to the public or limited to use within an organization for maintaining its internal knowledge base.

That's exactly what we're utilising Github's Wiki for - a knowledge base to define any decisions we make along the way, as a glossary of concepts we learn about during our journey, and as a valuable, ever-growing public resource for others to use for whatever reason they have.

Projects

That last part of Github that we haven't touched upon yet is Projects. According to Github:

A project is an adaptable spreadsheet that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively.

So maybe there's nothing else we need to do in order to fully utilise Github, because a Project seems to be more of an aggregation tool than a creation tool. Either way, I haven't yet learnt what a Github Project board does, so this is on my to do list for our next meeting.

---

The main thing I've learnt from all of this is how immense Github is as a full project management system - no longer is it just a glorified version control with issue tracker - we're running our entire operation from here, including this blog, which is written as a post in the Announcements Discussion board and rendered to the website as HTML (when we have a website, that is).

There's no bloat, no faff, no nonsense and definitely no stress. It's a lovely tool that respects what we need to do by getting out the way and allowing us to remain creative.

[richardbirkin]

Here Here!