Table of Contents

Working in GitHub

The tl;dr (too long, didn't read) version of this document:

  • one plugin per repo
  • one author per commit (copy-paste code has it's own commit)
  • Use GitHub Flow
  • Push your commits every day.

When to create a repo

The "unix way" or "unix philosophy" of software development is to create very small or narrow-purpose tools that do one thing well and can be combined with other tools in unexpected ways. This is just one of the oldest examples (40+ years!) of the many rationale's for not creating large packages of software. We can't quite meet the standards of the unix philosophy creating wordpress plugins, but we can keep our plugins focussed and small.

Git repos must not contain more than one plugin.

Do not be shy to create more repos. If there is a concern about having too many repos, then you should create a repo that contains all of the other repos used just to create a development environment.

Committing Boilerplate and Forks

If you are using existing code, either by forking, copy-paste, or a code generator, be sure to commit the borrowed code in a separate commit. Do not mix your changes with existing code.

Use Issue Keys in commit messages

It's not always required, but especially if you are fixing a bug: put the issue key in the commit message.

If you have a bug that is Jira issue SUP-1234, then your commit message should read: "fixes SUP-1234 by adding missing comma".

This is really a lazy way of writing commit messages because you don't have to provide as much explanation.

Issue Keys are mandatory in merge-commits.

Our issue tracker is integrated with GitHub, so commits will be automatically linked to the issue.

Commit Often

Commits are a form of documentation that can be very important for debugging. In addition to code-comments, commit messages that are well written provide a line-by-line explanation of why that line of code exists. You can use git-blame on the command line, GitHub's "History" feature (when you view a single file on github), and also git bisect. All of these tools require good commits that do not contain too many changes in one commit.

Use your IDE

Most IDE's now have built-in visual git clients. Besides showing you a diff of your un-committed changes, you can selectively commit changes. This is your savior if you forget to commit often.

If you've made a lot of changes and realize you forgot to commit:

  • Review all of your changes in the IDE diff tool
  • Think about how the changes relate to each other and decide how many commits you need to make to make each commit focused and meaningful.
  • Highlight each individual change and stage them to be committed.
  • Repeat until you've committed all of your changes.

Use "Feature Branches" or GitHub Flow

This is an old term that I don't hear very much any more. But it is essentially what "GitHub Flow" is all about.

A Feature Branch is a repo branch that you create to accomplish a single goal, such as a new feature. A bug fix is another good example of a reason you will create a branch.

After the branch has been reviewed, and any changes that are needed after the review, you will create a Pull Request to have the branch merged into the master branch.

Get an overview of GitHub Flow here: https://guides.github.com/introduction/git-handbook/#github and here: https://guides.github.com/introduction/flow/