This week, I’m going to walk through how you can configure your WordPress plugin’s GitHub repository.
Hosting open source code on GitHub is great because it is an established platform that so many other open source projects are handled with. Most developers understand how to use the tools available and can easily contribute to projects within GitHub.
Much like Joost, I’ve seen too many WordPress plugins that lack many of the basic necessities that make up a good GitHub repository. If you have time, give his article a read, it makes some really good points.
Your GitHub Repository Should Be Filled Out And Inviting For Others
When you use all the tools that GitHub provides:
- Documented workflows and processes are easier to find
- It’s easier for others to understand how to get involved
- Deployments can be handled easily with Releases
- It promotes healthy discussion & triage
By cleaning up your repository and setting up a few simple things, you will begin to see the benefits of a well-structured project in GitHub.
Here’s how, step by step:
Fill Out Your Repository’s Details
When you first create a new repository (or in your already established repository), take a few minutes and actually fill in the description.
This is one of the first things seen by users when visiting the repository and it helps communicate the goal of the project.
Do you have a marketing website that explains your plugin’s benefit? Do you have a site dedicated to documentation?
This only takes a minute or two, but can also help you refine your own goals.
Spend Some Time Documenting Processes
Over the last decade working with WordPress I’ve seen and used code from hundreds of repositories.
I’ve learned that—most of the time—if a codebase doesn’t have a README.md explaining at least how to get started with a library or plugin, I may not spend much time with it.
If I’m comparing two plugins in WordPress, typically I’ll choose the one with more documentation.
If you want people to use your codebase or contribute to it, tell them how to use it.
Writing a quick guide to get started will help others, but more importantly, anyone you pull in to help you.
Use GitHub’s Built In Releases
This is one area that I see a lot of WordPress plugin’s fail to do effectively.
Releases are a great way to show users and contributors what changed between versions. They provide an easy way to link directly to the code that changed and who made the change.
Often, this link will be a PR that was merged which provides all the context around why the change was made. Just these references alone are important when users decide if they should update to the newest version.
Additionally, you can attach a zip of the plugin that’s the same version of the release so you always have a way to quickly grab a version of your plugin at a particular step (pre-compiled too so you don’t have to fight with dependency issues).
Start using releases today.
In Summary
Your WordPress plugin’s GitHub repository is a great tool when it’s set up correctly.
Take some time this week and just start filling out the details.
Add some documentation or a getting started guide or set up some Github Actions for deployments.
It doesn’t all have to be done immediately, but start thinking about the ways you can start implementing some of these things. You’ll have a great repository soon!
