StripeCon New Zealand 2017 - Danae Miller-Clendon - Building SilverStripe modules to represent your company

toast.co.nz

toast.co.nz

Building SilverStripe modules to represent your companyDanaë Miller-Clendon

toast.co.nz

Who am I?

● SilverStripe developer for just over four years

● Currently work for Toast

● Developing with SilverStripe since ages ago

toast.co.nz

Building SilverStripe modules to represent your

company

toast.co.nz

Who is this for?

● Freelance developer making your own modules

● Developer working for a company

● Someone from a company

toast.co.nz

Presentation purpose

Making modules and slowly upgrading them is almost a given

for anyone working with SilverStripe.

● Add-Ons directory

● Open source

● GitHub issue tracking

● Community

toast.co.nz

Presentation overview

Choosing which style works best for you and your company

● Open Source vs Private

● Brand

● Maintenance and ongoing

development

toast.co.nz

Open Source

toast.co.nz

Open source modules

Benefits

● Available to the community

● Others can make suggestions

● Pull requests for

improvements and bug fixes

● Increase brand awareness with

good modules

Drawbacks

● Available to the community

● Others can make suggestions

● Pull requests may never come

● Bad modules can tarnish your

brand

Licensing

● How restrictive do you want to be?

● BSD License

● Use one that works for you and your company

silverstripe.org/software/bsd-license/

Maintenance

Maintenance

toast.co.nz

Semantic versioning

● 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

database fields

toast.co.nz

Issue tracking

● 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

toast.co.nz

Issue tracking

Allowing contributions

● CONTRIBUTING.md file

● Smaller changes are easier to

automatically merge

● Larger pull requests require some

QA

docs.silverstripe.org/en/4/contributing/

CI Tools

● Unit tests

● Scrutinizer / Travis

● Add-Ons rating

toast.co.nz

Private modules

toast.co.nz

Private modules

Benefits

● Can have very specific features to suit particular projects

● More control over the general direction of the project

Drawbacks

● 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

Licensing

● Can be more restrictive than open source

● Depending on your client, it may need

tweaking

● LGPL-3.0

● Other GNU General Public Licenses

opensource.org/licenses

toast.co.nz

Private modules

● Private repository● Access● Package manager

Structure

Private repository

● GitLab

● BitBucket

● Private GitHub

toast.co.nz

Satis

● Install Satis on your server

● Give access between Satis server and your private

repositories

● Poll for changes with Satis

● Add a reference in your composer.json to your Satis

website URL

blog.servergrove.com/2015/04/29/satis-building-composer-repository/

getcomposer.org/doc/articles/handling-private-packages-with-satis.md

toast.co.nz

Public or private?

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 :)

toast.co.nz

Brand

toast.co.nz

VoiceConsider the language you use, how you present yourself, and how

colloquial you choose to be

toast.co.nz

Documentation

● Resolves issues before they are raised

● Professional look

● Regularly updated documentation makes for a

fantastic module

● Keep it lighthearted and friendly

● Tell and show your readers what to do

github.com/thejameskyle/documentation-handbook

toast.co.nz

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

github.com/thejameskyle/documentation-handbook

github.com/praxisnetau/silverware-iconsetfield

toast.co.nz

API DocumentationAccurate, 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 examplesLever API

Good interface, specific examples

API documentation examples

toast.co.nz

API ReferenceResources

readme.io

swagger.io

contributor-covenant.org

github.com/thejameskyle/

documentation-handbook

Documentation imagery

● ScreenToGif● Use icons and images● Screenshots for CMS documentation

Dedicated website

Brand in issue tracking and response

● Be helpful and polite● Assume the user has minimum experience

Extra additions

toast.co.nz

Working on modules

toast.co.nz

Module direction

● Who determines the direction of your modules?

● Take clients into consideration

Workflow

● Roadmaps

● Pivotal

● Agile workflow

toast.co.nz

Losing trackHow to avoid burying modules

Put aside time each week or month

to work on modules

Keep your in-progress modules

front-and-center.

toast.co.nz

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

help.github.com/articles/creating-releases/

toast.co.nz

In conclusionLife happens.

toast.co.nz

References

material.ioreadme.iogithub.com/thejameskyle/documentation-handbookgithub.comgitlab.comsemver.orgcontributor-covenant.org

toast.co.nz

Thanks!

Toast LtdLinda at Toast for the slide designMaterial.io for icons