William Shepherd
by Glen Young

Maintaining an open-source project

This morning I read a short article on the maintainer of GitHub desktop, William Shepherd. For some reason, I kept seeing the article everywhere so eventually I surrendered to it. The post had a number of good points but the highlight for me was the advice to anyone maintaining an open-source project:

  • Have a clear vision of what you’d like your project to accomplish and be open to refining it when it makes sense
  • Have a detailed README that includes information on how to contribute to the project, submit bug reports, and a code of conduct
  • Work hard to make your project inclusive of all people from the start
  • Make your project easy to implement by eliminating the amount of work potential contributors have to do to build and run your project
  • Don’t put the needs of your project ahead of your own

You can read the full article on GitHub’s blog.


Colour Game Screenshot
by Glen Young

I made a thing – Colour Game

I made another thing in JavaScript as part of the course I’m doing. This time it’s a simple colour picker game. The code is still very rough but the app is effectivly working. If you want to see it in action you can play the current version.

The idea of the game is the player is presented with up to six coloured squares and an RGB value. They player then has to pick the square that matches the RGB value. There’s an easy (3 colours) and hard (6 colours) mode too, so you can vary the challenge of the game.

If you’re interested in the code (which is currently terrible) or you’d like to report a bug, take a look at the projects GitHub page.

Committed
by Glen Young

Commitment issues

You’ve been spending plenty of time together. You’ve had your ups and downs. As time’s gone on you’ve realised you like the way things are going and it’s time to commit.

Writing effective, communicative commit messages can make the world of difference to other members of your team. Just as with code comments or clear variable and function naming, good commit messages are worth putting some thought into.

First and foremost focus on communicating why the changes are being made. It’s easy to think commit messages are actually about what has changed, but reviewing the code will show you that. Why the code has change lets people know the intent of the change rather than the details of it. Good examples of commit titles are:

  • Update interface to the new branding
  • Add Dutch translation
  • Remove reference to Batmans true identity
  • Add GDPR compliance message

Once you’ve nailed your title follow up with a good description. For example:

Remove reference to Batmans true identity

The copyright text on Batmans website specifiys the copyright holder as “Wayne Enterprises”. This suggests that Batman has some association with the organisation. This update removes all connection between the two entities, protecting all parties. This fix addresses issue #391.

As you can see this message doesn’t contain any details about the code. It clearly highlights why the commit is being made and also connects the commit to a reported issue if one exists.

beatify
by Glen Young

Every team needs a beauty routine

Over the years everyone will develop their own beauty routines when it comes to their individual coding.

While it’s easy to become attached to how you like to format your code, in a team environment it’s really important to share the mirror with teammates.

Having an agreed set of standards on how the code will be formatted goes a long way to improve its legibility. If one person is using tabs, and another spaces, then things can get ugly fairly quickly. Of course, this sort of formatting can be done manually, but we’re not wild animals so we can just get the computer to do most of the work for us.

Most text editors have multiple plugin options to take care of this sort of thing. There’s even a standard called editorconfig that allows different developers to work on different projects, even using different editors. Using the editorconfig standard a developer can automatically conform to whatever the standard is for a particular project without much of a song and dance.

The two most popular beautifying plugins are:

Believe it or not, you can actually use both of these at the same time. There are some good details as to the how’s and why’s of that on CSS-Tricks.com

Iron man has Issues
by Glen Young

More on issues

The more you understand an issue the better equipped you’ll be to solve it. When I was creating issues in GitHub for Score Keeper, something about the process felt a bit lacking. A developer needs specific details and the system wasn’t working to deliver them.

Even the issues I’d submitted lacked the detail for someone (other than me) to address the problems outlined. I’d previously contributed to Gutenberg, and I noticed the team had templates for recording issues. As it turns out, this is a standard feature in GitHub.

To improve my practice, I’ve enabled the two default templates provided by GitHub. The first is for reporting bugs like “Max score change doesn’t affect victory formatting” and the second for requesting new features like “Interface needs styling”.

Click the “Set up templates” button in your repos settings tab to get started with issues templates

In time I’ll be updating the current issues submitted to conform to the templates. Any new issue will get the right template depending on its nature. A bug will get one template, while a feature request will get another.

Any tool that can improve communication like this is worth its weight in gold.

Issues
by Glen Young

We’ve all got issues

Since I’ve been learning JavaScript I’ve been making an effort to do things as if I was working with others. The idea being that any project of meaning is very likely a collaborative one.

To my mind understanding how to effectively work with others on a coding project is as important as the coding itself. Also understanding how people work is always good when managing people is part of your professional life.

To that end, since I’ve recently created an “app” and put it on GitHub, the obvious next step was to record any issues with the app. So far there are three, but I suspect there are plenty more.

  1. The interface needs styling
  2. What constitutes victory isn’t clear
  3. Max score change doesn’t affect victory formatting

Over time I aim to chip away at these and any other reported issues. Of course being open-source, it’s entirely possible others may do the same. Which would no doubt teach me something too…

2 out of 3 aint bad
by Glen Young

I made a thing – Score keeper

I’ve been doing a web development course for a few months and today I made my first thing that actually does something. Nothing amazing mind you, but it’s a start.

Do you ever have the need to keep score in a best 2 out of 3 kind of way? Me neither, but here’s a web app that does it regardless  🙂

At some stage, I’ll pop it on a web server and make it live for anyone to use. For now, if you’re interested in the code, take a look at the GitHub repo or you can download it directly.

Update: The app’s now live. Give it a try.

gutenberg press
by Glen Young

Learning from a 579-year-old printing press

Gutenberg is the name of WordPress’ new editor and like its namesake, the Gutenberg printing press, I think it’s going to be a big deal.

Recently I’ve been committing real time to upskill in web development. I wanted to go way outside my comfort zone as an opportunity to grow. So contributing to an open-source project like Gutenberg seemed like a good place to start.

Things I learnt from doing this:

1.  I have no idea what I’m doing, but I can learn anything – Seriously I know nothing! So, when I started looking for something to do to add value I needed something fairly basic. Thankfully Gutenberg is newbie friendly. This presents itself in a number of ways (see point 3) but the first sign of it was the “good first issue” tag on GitHub issues. As the name implies, this shows issue which are good entry points into making a contribution. So after a few days of self-doubt, I picked one and started working on it.

2.  There’s way more to contributing than code – The first thing I needed to do was get my development environment setup. I’d been learning Javascript for a while so I figured I’d be in good shape but in reality, I was miles away. I needed to setup docker, node, NPM and use GitHub with other peoples code. I’d never done any of this before. So before writing a line of code I already had a lot of new learnings. When I did get to coding, I thought I was in for some simple CSS changes. It turns out Gutenburg is using a CSS pre-compiler called Sass. Surprise! I’ve never used that before either, so back to Google University for another lesson.

3.  The community is incredibly supportive – Given the first two points, I needed a lot of advice. When I got stuck or submitted some code there was the community willing to advise and guide on how I could improve. They are also super accessible and transparent, I’d say more so than most work environments I’ve been in. Slack meetings and GitHub issue comments brought genuine insight, and as a result, skill growth. I never would have got any of it without the patience and generosity of the group.

4.  Having your code on millions of websites is a buzz – It’s strange in retrospect, but when I started doing all this it hadn’t occurred to me that if I managed to deliver something it would end up on millions of websites. Now that I have actually done that it does have an addictive feel to it. However minor my contribution is, the scale of the end result is truly massive.

I think at this point it goes without saying I would highly recommend contributing to a project. Regardless of your skill level, there is something to be learned and value to be given and received.

Roxette
by Glen Young

Listen to your heart

JavaScript is responsible for the behaviour of your website/app. At the heart of affecting the behaviour of the page is listening for user interaction events. These are things like button clicks, key presses and drags and drops.

To do this, first we select an element then we add an event listener. To add an event listener we use the “addEventListener” function like this:

var button = document.querySelector( "button" );

button.addEventListener( "click", function() {
  console.log( "SOMEONE PLAY SOME ROXETTE!" );
} );

A common pattern is to add event listeners to a set of elements, like each item in a list so each item is clickable. The code for this would look like this:

var listItems = document.querySelectorAll( "li" );
for ( var i = 0; i < listItems.length; i++ ) {
    listItems[ i ].addEventListener( "click", function () {
        this.style.color = "pink";
    } );
}

You can also add multiple event listeners to the same element. So, for example, you can listen for a hover and a click on the same button and take separate actions for each. Listen events are very powerful and a great addition to your JavaScript coding toolbelt.

concerns dude
by Glen Young

This is our concern, Dude

In web development, there’s a concept called “the separation of concerns” between your HTML, CSS and JavaScript. Each language plays a role in web development and it pays to remind ourselves what these roles are:

  1. HTML = Structure
  2. CSS = Appearane
  3. JavaScript = Behaviour

There are some overlaps between them, but this should be minimised wherever possible.

There is some overlap between HTML, CSS and JavaScript but this should be minimised wherever possible.

For example, while JavaScript can affect individual CSS styles but it’s good practice to define classes in your CSS files instead. Then you can use JavaScript to call those classes like this:

<!DOCTYPE html>
<html>
<head></head>

<body>
<div id="concerns">
  <ul>
    <li>JUST BECAUSE WE'RE BEREAVED DOESN'T MEAN WE'RE SAPS!</li>
    <li>Sir, please lower your voice</li>
    <li>Hey man, don't you have something else you could put it in?</li>
    <li>That is our most modestly priced receptacle.</li>
    <li>GODDAMNIT! IS THERE A RALPH'S AROUND HERE?!</li>
  </ul>
</div>
</body>

</html>
.concerns li {
  font-weight: bold;
  font-size: 100px;
}
var myConcerns = document.querySelector( "#concerns" );
myConcerns.classList.toggle( "concerns" );

This way the CSS is still where the appearance of the page is manipulated and the JavaScript is still handling the behaviour component. Following this sort of structure makes it easier for your fellow developers (and you) to know where to do what in your code.