stripecon new zealand 2017 - danae miller-clendon - building silverstripe modules to represent your...
TRANSCRIPT
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
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 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/
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
Allowing contributions
● CONTRIBUTING.md file
● Smaller changes are easier to
automatically merge
● Larger pull requests require some
QA
docs.silverstripe.org/en/4/contributing/
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
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
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
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
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
References
material.ioreadme.iogithub.com/thejameskyle/documentation-handbookgithub.comgitlab.comsemver.orgcontributor-covenant.org