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.

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

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.

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…

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.

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.

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.

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.

DOM DOM DOM

Playing with the DOM is all about adding interactivity to your page. The DOM (Document Object Model) is the interface between your JavaScript and your HTML+CSS. The browser takes all the elements of your page and turns it into a JavaScript object.

All the elements of the DOM for your page are contained in the object “document”. You can show everything in “document” by using this command in your browser’s console:

console.dir(document);

Working with the DOM is similar to CSS. This is because you select an element then you manipulate it. Here’s an example of what I mean:

var batmanComments = document.querySelectorAll( ".batmanComments" );

In the above example, we are selecting all elements with the class “batmanComments”. Now to do something with our newly selected elements:

var length = batmanComments.length;
for (var i = 0; i < length; i++) {
    batmanComments[i].textContent = “Ironman sucks”
}

This code replaces the contents of each element in the “batmanComments” array with the string “Ironman sucks”… because maturity isn’t Batman’s strength.

If you want more details on working with the DOM, MDN is a good place to start and an even better reference as you’re learning.

GitHub flow

I’ve recently been attempting to contribute to some open-source GitHub projects with varying degrees of success. One thing that’s extremely useful to do before you start contributing is to develop a basic understanding of the standard GitHub workflow.

It’s not especially complicated but it can be a real faff if you don’t do it correctly from the start.

Step 1 – Clone the repo

The first thing you’re going to need is your own copy of the project to work on. You do this by cloning the repo to your local machine where you’ll make your changes.

Step 2 – Create a branch

Now you’ve got a local copy you’ll want to create a separate branch for your specific contribution. For example, if you’re working on issue #3271 and issue #3244 you’ll want to create separate branches for each issue. It’s a good idea to name this something like fix/issue#3271 and fix/issue#3244 so you know which branch to submit for what issue once you’re done.

Step 3 – Make commits

Once you’ve made your changes within the appropriate branches make your commits. Commits tell the story of your changes, be sure to write clear concise comments that communicate your intent to other developers reading them.

Step 4 – Submit a pull request

Once you believe you’ve completed your changes create a pull request to submit them. Create one pull request for each issue and corresponding branch you’ve created. Pull request are a way of notifying the projects “owner” of your proposed changes for consideration.

Step 5 – Discuss and refine

It’s likely upon review there will be some conversation around the code and changes. Others may have ideas on different approaches and/or improvements to the update. You can continue to make changes and improvements to refine your solution as a result of these discussions. Just keep making those commits.

Step 6 – Deploy

This part you’re likely to be less involved with. If and when the “owner” decides to use your code they will likely deploy it into the master branch where it will then be tested along with all the other changes made in that round of updates. This is were things get exciting.

Step 7 – Release

Assuming everything is tickety-boo your code is then included in the next production release leaving you with a sense of satisfaction from having helped to make the world a better place one pull request at a time. Don’t forget to be grateful for all the help along the way. Open-source is all about community coming together, so remember to give high fives all around.