Hey everyone! I’m Danae and I’m a web developer at a great company in Auckland called Toast. I’ve been in the industry for about six years, roughly four of which I’ve been working exclusively with SilverStripe. In that time I’ve worked on various modules, made plenty of mistakes, and may not know enough to tell you how to do it right, but I know just enough to hopefully get you excited about making modules.
As developers working for a company - or even freelancers, you may find yourself falling into that monotonous routine: build website, test website, launch website, continuous maintenance. Build another website, test website, launch website, etc etc.
Often you’ll find yourself taking bits of functionality and making modules of your own. You then have a decision you can make - should you release those modules to the community? Or would you like to keep some secrets for yourself?
Once making the leap to creating real SilverStripe modules, you take on the responsibility of maintaining and documenting those modules. But how do you find time in your working week to do this? “Non-chargeable time” has been known to send management into fits of hysterics.
Now you know what this talk will be about and vaguely who I am. So how does this presentation relate to you, and how can it help you? You might be a freelance developer, or someone working for a company. You want to be able to make or plan your own SilverStripe modules, or harness the open source community to help you produce and improve them.
Whether you’re working for a company or you’re a freelance developer using SilverStripe, there’s usually one thing you have in common - the drive to self-improve. To learn, to make your code better every month, every week, every day. To look back at something you wrote a month ago and screw up your face, and want to bury it so it may never see the light of day.
Making modules and slowly upgrading them is almost a given for anyone working with SilverStripe. Since we have the Add-Ons directory and our community, plus the open-source nature of SilverStripe, you have the option of displaying your code for the world to see. And comment on. And mark issues with no detail or screenshots. Or note a fix but never make a Pull Request. I digress.
You may be at various stages of this inevitable road. You might be the new developer who has just learned how to make modules - yes, you can make folders in the root! Now, forget all of that, SS4 moves it to the vendor folder.
You might be the developer who has made a well rounded module, released to the community, then instantly forgotten about it.
You could be sitting on the fence about your module - it has some really interesting stuff. But it’s just awfully and suspiciously specific to one of your clients.
You could be a manager sitting in the crowd, coming to the slow realisation that your developers do indeed have autonomy, can and will release their code to the community, and outnumber you about 20 to one right now.
I feel that regardless of whether you are in management, marketing, or development, modules play a big part in the SilverStripe websites you produce. Part of that journey is deciding how or if you want to release your modules to the public, what sort of maintenance and ongoing development commitments you can make, and how the modules you develop affect your branding.
This talk will be split into three sections - Open source vs private, brand, and maintenance with ongoing development.
The first section will describe the merits and disadvantages of both forms of SilverStripe module. Then, I’ll talk about brand, and how you can represent yourself or your company in a positive light with the modules you create. Finally, I will touch on ongoing maintenance and development of your modules.
We’ll start by chatting about open source. The good, the bad, and the unsquashed commits.
Open Source is listed as one of the four core drivers behind SilverStripe. For a lot of instances making your modules open source is a great idea. You open your code to the community, where other developers can make suggestions and improvements, and find bugs for you. Releasing a number of reliable and helpful modules attached to your brand is a great way to increase your presence in the community.
On the other hand, these benefits can work against you, or be reasons in and of themselves to avoid releasing your modules to the public.
That being said there are plenty of things to take into consideration and responsibilities you take on after releasing your module to the public.
Having a module open source gives back to the community. Other developers can make suggestions and report bugs. They may even make pull requests to help you out. Having your own name or your company’s name against a highly rated module reflects well on you and your brand.
At the same time, the module is open to the community. Other people can try and determine where your module should go. Pull requests may never come in, leaving you to handle it all alone. And a poorly rated or badly represented module can tarnish your brand.
Once you decide that you’ll release your module to the public, there are a few things you’ll want to do.
One of the first things you may need to consider is what sort of license you’ll want to attach to your module.
The SilverStripe core is based on a modified BSD license - one of the least restrictive licenses. You can choose to use the same sort of license, or implement something more restrictive on your module. The BSD license reflects the values of open source and SilverStripe very well - but at the end of the day it’s up to you or your company to choose a license that will work best for you.
If you’re working for a company you may wish to strike up a conversation with them on the merits of a looser license for your software. I can almost hear the managers in the audience crying out, “Not my IP!”
You’ve sorted your license type out you’ve decided to give back to the community and share with them all your precious code child, lovingly hand-crafted. You’ve stayed up late far too many times making it just right.
With a happy heart you upload it to GitHub. You don’t need release branches, it’s perfect! You don’t want tags, it already works with the most important versions of SilverStripe! (3.6 is still relevant, right?)
Little more than a week and a handful of downloads later the little notification bubble pops up.
While not exactly helpful, you’ve been rudely awoken from your perfect module dreamland. Your module is not perfect, and people will tell you so.
Fortunately most issues that crop up aren’t as unbelievable as this one.
So how would you go about improving your fresh off the press module?
The first and probably easiest thing to implement is semantic versioning. You could keep your module sitting on the master branch forever, and just tell everyone to put down an asterisk in their composer.json file.
In reality, even with the simplest modules, semantic versioning is quite crucial.
Push new tags as you see fit. You’ll learn to find a nice balance between too many or too few. Take a look at semver.org as it will tell you how basically everyone else is using semantic versioning. Always make a major version when you change any database fields. Don’t ask me how I know.
As people actually start using your modules, they’ll likely find bugs. If you’re very lucky, they’ll actually report them. So don’t feel downhearted when that little email slips in your inbox with the little issue number on it. Rejoice! For there are probably many bugs that are happening yet no-one has thought to report them.
When an issue comes in, take your mind back to that tech support job you held while fresh out of uni. Is this bug reporter personally paying you? No. But they are helping you iron out those edge cases. So be polite, be friendly. And since they aren’t paying you, you can absolutely ignore them if they are being a bit obstinate.
At the end of the day, this module you’ve produced is representing your brand. It might be attached to the company you work for, or to your personal handle. Always try to see that side of things when the only update you get on an issue is, “sorry, still not working”.
Mercifully, there are people out there who take the time to fork your repo, squash their commits tidily, and make a pull request back to your code which hopefully actually fixes the issue and doesn’t create new and exciting ones.
Most PRs seem to be quite straightforward and simple fixes - it is a bit scary to be messing around in someone’s code then offering it back to them and telling them it’s all better now. Creating a Contributing.md file will help potential contributors make pull requests.
When the bigger ones come in, they can take a little while to work through and ensure they are stable, but you’ll be buying that developer a round or two at the next conference pre-drinks.
While you could manually screen these pull requests for bugs, checking that everything is still in working order is a lot easier to do automatically.
For small and simple modules you may not see the merit in creating unit tests. If you can find the time, absolutely make them. You get a shiny badge if they pass! And not only will it keep your brain thinking about how new features will be affecting existing functionality, it allows you to easily filter incoming pull requests.
Travis CI is a tool that is relatively straightforward to set up and attach to your GitHub repo. These tools are automatically run during pushes, and are run against incoming pull requests. Code that comes in broken will probably need some work.
SilverStripe modules are automatically pulled in to SilverStripe’s own module directory, and are subsequently rated. Having configured Travis, scrutinizer, and putting some documentation in will boost your score by a whole lot. Users looking for the best module to help them with a task will look for generally three things - total downloads, when it was last updated, and if it has a good rating. We really can’t resist that happy little green circle!
While there are many merits to making your module publicly available, there are certainly a few reasons why you’d need to make your module private.
Generally it comes down to your client or your company. This module could be pretty good, but if it is very specific to the needs of the client you’re working with, it may not be suitable for public release. An example might be an API you create to facilitate functionality on your client’s website.
It can also give you more control over the general direction of the module. You don’t need to accept pull requests or address issues from other developers.
At the same time, this gives you or your team the sole responsibility of fixing bugs. You will need to manage the services you take for granted, like packagist. And it can absolutely give you less control over the direction of the project. Your client could end up determining what new features should be added, and which ones taken away.
If you decide to keep your module away from the public space, you still need to consider licensing.
Even though you expect no-one outside of yourself or your company to be viewing the actual code, for the sake of code hand-off or eventual public release, you’ll want to create a license that is appropriate for your module. It will probably be less open than a public module. You may also need to consider if your code can be handled by your client or company - you may give other developed access to it in order for a select few to implement it in their own projects.
Take a look at the licenses page on the Open Source.org website. It lists out licenses by how restrictive they are, and you can take your pick. I feel something like LGPL-3.0 is a good starting point for a private module.
An open source module is quite easy to make available to the community. You ensure it has the correct module structure, then plop it onto GitHub and sync it with Packagist. That’s bare minimum. With private modules the process is slightly more complex.
You’ll need to consider where you will store your code, who you give access to, and how you actually pull those dependencies into your composer-controlled project.
The first thing you need is a code repository that will be inaccessible to the public. GitLab, Bitbucket, or private GitHub repos are an option. You can give access to specific people to actually contribute to the code. You won’t get any forks or pull requests except from those select people.
While Packagist is relatively easy to set up and integrate with something like GitHub, a little more effort is required for private repositories.
A popular choice is Satis, which works the same as Packagist.
There are a number of helpful guides online which will walk you through this process step by step, so I’ll just give you a quick overview.
On your own webserver, you install the Satis software. Using a json file, you tell Satis which repositories you want it to poll. Using SSH key pairs and some token authorisation, you can have Satis read your private repositories.
You then set up a daemon to poll every couple of minutes for changes to your modules.
In your own projects, you can add another line to your composer.json which will let composer know where to find the packages you’ve listed.
Depending on your requirements, you may be able to settle with a public module, or go through the trouble of setting up a private one. At the end of the day, you’ll use versioning, issue tracking, branching and deploying to keep your module up to date for its purpose.
Choose which method will work best for your team, brand, and company.
Private modules for client-specific functionality
Public modules to contribute to the community :)
How you present yourself and your modules is certainly optional, but it helps convey legitimacy and trust. This may lead to more people downloading your modules and subsequently more bug reports, so tread carefully.
In a nutshell, voice is the kind of language you use in your branding and wording. How you present yourself, and how colloquial you choose to be. This is an optional thing to consider when writing documentation for your modules.
While the existence of a readme.md file will give you bonus points on SilverStripe’s module rating system, it’s vitally important for the users who will be installing your module. Good documentation keeps users away from the issue tracker, and will lead even the most beginner developer to install your module successfully.
For the simplest modules you’ll need to be able to describe how to configure, implement, or use your module in the CMS. For more complex modules, you’ll need to expand upon your simple README.md.
These points are just a few of the excellent pointers you can find in the Documentation Handbook by James Kyle. It’s a general guide to writing better and more helpful documentation, to be more inclusive with your voice, and how to format and organise your documentation effectively. I highly recommend you take a look!
Learn some simple markdown and divide your documentation into sections. Cater your index page to all levels, and then offer more detailed documentation in other sections. Developers will go digging for more specific documentation!
API documentation differs from CMS user documentation. Structure your documentation appropriately and go into as much detail as you need. As long as it is structured well and laid out coherently, you can fit a lot of detail without overwhelming the reader.
API Documentation requires structure, regular updating, and accuracy. I’m sure you’ve all experienced poor API documentation that can lead to dire consequences.
If your code is fairly well structured and commented, including docblocks, there are a few online services and software that can format API documentation from your module itself. Otherwise you can do wonders with markdown tables and clever linking.
This is a screenshot from the Lever API documentation. It could potentially be autogenerated - the layout is very concise and everything is accurate and thorough. As you scroll, the menu on the left follows your location. It keeps descriptions short and to the point, and provides specific examples of the kind of API calls you can make.
While it has extensive detail on the types of endpoints and methods available, it also has model references. This is vitally important so you can show your users what kinds of data to expect in a response.
The Workable API is a similar service, however they have used Readme.io, a software as a service that automatically compiles your codebase into structured and segmented API documentation.
The Workable API is a RESTful API - Readme.io organises the endpoints into their HTTP methods. If you are creating a RESTful API, documentation like this is critical.
Readme.io also provides status and error codes in their real examples, so you can see what kind of error responses you will need to handle.
The icing on the cake is the ability to test API endpoints and data in the actual documentation website.
Markdown and readme files have their uses, but for API reference as complicated as this, you may want to consider using a separate service.
I’ve pulled up a couple of websites that will take your codebase and create the documentation for you. There are numerous services available out there - some free, some not.
Another fantastic resource and definitely worth a look is the Contributor Covenant. Sometimes we fail to consider what kind of language we’re using in our documentation, and fail to think about how our words affect the users we are trying to get to install our modules. It’s possible to discourage potential contributors if we use language that excludes them, or become thoughtless with our words. The website listed above explains the purpose and aim of the Contributor Covenant far better than I can - so make sure you take a look.
This also can heavily influence how you write user documentation.
User documentation is for the CMS users of your site, so screenshots can be rather helpful. Even better, use something like ScreenToGif to show the user what to do instead of just describing it.
If your module is large enough, it can warrant its own website. You can see this in the larger E-Commerce modules (SwipeStripe and SilverShop). Reflect the documentation from your GitHub repository here, or expand on it. More than anything your brand will be affected by a dedicated website. You have full control of the design, and what kind of voice you choose to use.
How you present yourself in the way you respond to bug reports can reflect your brand well, or tarnish your reputation somewhat. Be helpful and polite, and never discourage new developers by talking down to them.
If you work for someone else, it could be necessary to have a discussion about how you want to present yourself. Obviously, the issues will still need to be solved, but swearing and jesting may or may not be appropriate to attach next to your company’s name.
Whether or not you’re working for someone else, you’ll want to consider what sort of direction your module should take. In most instances your module will be something small. You may not need anything beyond a simple maintenance and upgrade plan.
If your module is larger you’ll inevitably need to make decisions on how certain aspects of it will be developed. You may need to leave some things out, or choose to prioritise features for development. For example, a client may require something that you can work into your module. Generally speaking this can bump that feature up to the top of the list.
Create a roadmap for your features, and use a program like Pivotal or a classic sticky note board to manage your icebox and bug tracking.
Documentation is often easily ignored, as you probably try and get the module developed and finished as soon as you can in order to get back to chargeable client time. Documentation is still essential!
Occasionally client work will get in the way. And by occasionally, I mean all the time. It pushes out those lower priority things like documentation, new releases, and bug fixing on old modules. So how do you avoid completely abandoning projects?
You’ll have to work hard at it. Being unbearably busy is something we all seem to have in common in the web development industry. If you can, book a half or full day, once a week, dedicated to R&D and improving modules or documentation. Keep post-it notes of your in-progress modules and stick them by your computer screen, so you don’t forget to keep assigning time to them.
Yes, sometimes you will legitimately be too busy to work on modules - just don’t leave it so long you forget your direction. Treat your module like a client project - set yourself deadlines, goals, and budget.
Use tags appropriately. You can mark your module as pre-release in GitHub and use Release Candidate and alpha or beta tags before full, stable release.
Make sure you keep on top of managing your dependencies. Keep an eye on other modules and the core releases - you don’t want your module falling into obscurity simply because you’ve locked your dependencies down to older versions of SilverStripe.
When I found out I’d be presenting this talk, I got very excited. I thought about all the modules I’ve been slowly working on, and how much I’d be able to do to them to get them ready to show in this talk. I was halfway through some API documentation when work and life got busy - very. Busy. And my spare moments were spent working on the presentation itself! But that’s the way the web industry is. I’m not disappointed I couldn’t show you a fully fledged API documentation. If anything it reinforces some of the things I’ve touched on today.
Life happens, and work happens, and all we can do is work through it and come out the other side with a piece of code we’re actually quite proud of.
At the end of the day, you can disregard everything I’ve said. You choose how your modules are developed and presented.
StripeCon New Zealand 2017 - Danae Miller-Clendon - Building SilverStripe modules to represent your company
Who am I?
● SilverStripe developer for just over four years
● Currently work for Toast
● Developing with SilverStripe since ages ago
modules to represent your
Who is this for?
● Freelance developer making your own modules
● Developer working for a company
● Someone from a company
Making modules and slowly upgrading them is almost a given
for anyone working with SilverStripe.
● Add-Ons directory
● Open source
● GitHub issue tracking
Choosing which style works best
for you and your company
● Open Source vs Private
● Maintenance and ongoing
Open source modules
● Available to the community
● Others can make suggestions
● Pull requests for
improvements and bug fixes
● Increase brand awareness with
● Available to the community
● Others can make suggestions
● Pull requests may never come
● Bad modules can tarnish your
● How restrictive do you want to be?
● BSD License
● Use one that works for you and your company
● Practical for even the simplest projects
● Push tags when you see fit
● Follow guidelines on semver.org
● Always make a major version change when modifying
● Be thankful when you get an issue report
● They are helping you
● Be polite and friendly
● At the end of the day, you can ignore them
● Can have very specific features to suit particular projects
● More control over the general direction of the project
● No one else but you and your team can fix bugs
● Services need to be self-managed
● Less control over the general direction of the project
● Can be more restrictive than open source
● Depending on your client, it may need
● Other GNU General Public Licenses
● Install Satis on your server
● Give access between Satis server and your private
● Poll for changes with Satis
● Add a reference in your composer.json to your Satis
Public or private?
Choose which method will work best
for your team, brand, and company.
Private modules for client-specific
Public modules to contribute to the
Consider the language you use, how you present yourself, and how
colloquial you choose to be
● Resolves issues before they are raised
● Professional look
● Regularly updated documentation makes for a
● Keep it lighthearted and friendly
● Tell and show your readers what to do
Markdown/Linking within GitHub
● Cater your index page to all skill levels
● Go into detail in separate sections
● Use screenshots in CMS documentation, and code
snippets in user reference
Accurate, detailed, to-the-point
● Simple API’s can take advantage
of Markdown tables
● Automatic API reference
documentation works well for
more advanced modules
API documentation examples
● Use icons and images
● Screenshots for CMS documentation
Brand in issue tracking and response
● Be helpful and polite
● Assume the user has minimum experience
● Who determines the direction of your modules?
● Take clients into consideration
● Agile workflow
How to avoid burying modules
Put aside time each week or month
to work on modules
Keep your in-progress modules
Working with releases
● You can push as many tags as you like
● Mark releases as pre-release if they aren’t stable
● Don’t lock your dependencies down unless you need to
● Keep on top of your dependencies