You've got some awesome code that you've written, which you want to share with the community. Sure, you could simply post it on GitHub and be done with it, but is that the best way to share your work? What are the additional steps needed to share your code in a way that it will actually get used by the larger world? I'll discuss options for hosting , licensing, versioning, packaging, documenting, building, testing and even contributing to your code. All the things that will make someone else say - I want to use this!

1. CREATING AND
MAINTAINING AN
OPEN SOURCE
LIBRARY
MILWAUKEE CODE
CAMP
NOVEMBER 16TH,
2019

2. ABOUT THE PRESENTER
Nick Schweitzer
 Managing Architect in the Modern Apps Practice at Concurrency
 20 Years of Consulting Experience
 Currently Using .NET, Azure, TypeScript, Angular, SQL
 Previous practitioner of C/C++, MFC, COM
 Some experience with many other languages and frameworks
 Adjunct Lecturer at Carroll and Marquette Universities
https://www.linkedin.com/in/nickschweitzer/
https://www.github.com/NickSchweitzer

3. WE’RE HIRING!
 Concurrency Is Hiring Several
Positions!
 Cloud Security Architect
 Software Architect
 Data Scientists
 Software Developers
 If You’re Interested – Go to
https://www.concurrency.com/w
hy-concurrency/careers
 Talk to Me After This Talk!

4. NOT A CODE
DUMP
 Hey look – I uploaded my code to GitHub – Its an open
source project! Right?
 Start By Thinking About Being a Project Consumer.
What do you want to see before you add a library to
your application?
 Check-in History – Is this library still actively
developed?
 Unit Test Coverage. Do they even have Unit Tests?
 Is there any documentation? Is it useful and up to
date?
 What if I find a bug? Is there someone who will fix it,
or someone who will accept my Pull Request?
 Is there a prebuilt package, or do I have to build it
myself?
 If you wouldn’t use a project without these things, then
why should you provide a project without them to
others?

5. WHAT ANY
PROJECT NEEDS
Source Code Control
Licensing
Versioning
Unit Tests
Code Coverage
CI/CD Pipeline
Package Management
Documentation
Maintainers

6. OPEN SOURCE
TOOLING CAN
BE FREE!
 Most of the services on this list have free
and paid for services
 Open Source libraries may qualify for free
accounts, as long as you use a public
repository
 The Lists I’m Providing Are Definitely Not
Exhaustive, Nor Authoritative
 Look at the features, limitations, and pricing
and evaluate them for your needs
 If you make different choices than mine, great!
Just choose something!

7. SOURCE CODE CONTROL OPTIONS
GitHub
The Default Option – Do I
Really Need to Describe
GitHub to you?
Azure DevOps
Public Projects In Public
Preview
BitBucket
Gives you access to other
Atlassian tools (Jira,
Confluence, Pipelines, etc.)
Unlimited Private
Repositories and 5 User
Limit (in the free version)
GitLab
Built In CI/CD
Project Issues Board
Chat

8. A BRIEF OVERVIEW OF LICENSING OPTIONS
 “I’m Not a Lawyer”
 Sometimes licenses are dictated by the projects you contribute to, or because you are creating a plugin for an
open source project
 You may not care about that much about licensing, but people consuming your application might.
 Common Options
 MIT License – Very Permissive
 GNU GPLv3
 Apache License 2.0
 What If I Choose Nothing?
 Your Source is Considered Copyright Protected and Restricted
 Don’t Know How to Choose?
https://choosealicense.com/

9. VERSIONING YOUR PACKAGE
 Once You Package Your Code and Make It Available Through NuGet or NPM – Versioning is
Crucial
 Semantic Versioning – https://semver.org/
 Ensure CI/CD is not pushing branches out to Package Repositories if not versioned
appropriately with –beta or –alpha monikers on the name.
 Think through your roadmap ahead of time, so that you aren’t bumping your major version
for every small breaking change, otherwise you will end up with Library v45.1.0

10. CI/CD OPTIONS
Azure DevOps
Public projects still in
Preview
AppVeyor
Fewer built-in
integrations, but YAML
build allows for custom
scripting using many
languages
Travis
.NET Builds with Mono or
Core on Linux. May have
issues if you require
Windows compatibility
for .NET Framework
libraries
CircleCI
Free version limits the
number of credits you
can have per week.

11. CODE COVERAGE OPTIONS
 CodeCov – https://codecov.io
 Uses OpenCover to perform code coverage analysis on Unit Tests
 Coveralls – https://coveralls.io
 Doesn’t Appear to Support Azure DevOps (Easily)
 Multiple Ways to Send Data Up, including OpenCover
 If Creating a Library that Supports Multiple Frameworks (.NET Framework, .NET Core, etc.) – Need
to determine if you want to perform unit tests and code coverage on all builds of your project, or
only on one, and which one.
 Do you have any #DEFINE blocks that run different code based on Framework version?
 Not all Code Coverage tools support merging of Code Coverage reports together well

12. PACKAGE MANAGEMENT
 Where Should You Deploy Your Code?
 GitHub Releases
 GitHub Packages – New!
 May Depends on What Language/Framework Your Code Is Meant For
 NuGet.org
 NPM
 PyPI
 Most Package Management Systems Have an API to Allow Automated Updating from a Given
CI/CD Platform
 Be careful to configure your build pipeline so that branches aren’t deployed to a package
management site

13. DOCUMENTATION OPTIONS
Read The Docs
• Ad Supported (Which
Some People Don’t Like)
• Can Use Markdown or
Sphinx
• Has Hooks To Auto Build
Documentation on Repo
Update
GitBook
• Can Only Use GitHub
• Has Hooks To Auto Build
Documentation on Repo
Update
GitHub Wiki
• Built Into GitHub
• Can Use Git to Update
Documentation Just Like
Code
• Folders Don’t Work Very
Well
• No Theming
• Only Supports MarkDown
GitHub Pages
• Static Website hosted on
Github.io
• Tied to a GitHub
username, instead of to a
Project

14. DOCUMENTATION
 Documentation should be in several forms:
 English language narrative documentation you thoughtfully create
 Library Reference Documentation – This can be auto-generated
 XmlDocMarkdown – Converts C# /// XML Comments to Markdown Files
 TypeDoc – Creates HTML from Typescript Comments. Plugin available to generate Markdown instead
 Samples & Quick Starts
 Sample Code
 Documentation Supporting the Sample Code

15. YAML EVERYWHERE
 YAML Ain’t Markup Language (or Yet Another Markup Language)
 It Appears to Be the Defacto Standard for Code Based CI/CD Configuration
 Most of the services discussed here allow you to configure them either through a web interface, or
through a YAML file along side your code.
 I Personally Recommend YAML Configuration over Web Configuration, as it can be branched and versioned
alongside your code. Your build process may need to change because of your code, and your configuration can
be tied to a PR or Branch appropriately.
 Most services require the YAML Configuration file to be named very specifically to be processed. Read the
documentation for each service carefully to find out.
 Be careful about having API keys in your YAML file checked into your repository. Some services (like
AppVeyor) have ways to encrypt API Keys.

16. YAML GOTCHAS
 YAML is Shockingly Complex for a Language Advertised as “Simple”
 The YAML Spec is ~23K words. JSON is only ~2K words. XML is ~20K words.
 There are Nine different ways to create multi-line strings. Each produce slightly different
behaviors
 Whitespace has meaning, but tabs are illegal. Differing whitespace can break your code, and
its not visible as to why. This makes it brittle.
 It’s not portable. Because the spec is so complex, different implementations treat the same
file differently.

17. THEN WHY ARE YOU TELLING US TO USE YAML?!
Documenting Your Build Process Using Code Is
Better Than Configuring Through a Web Site
• Build Process Can Be Versioned Along With
Your Code
• You Don’t Have to Manage Access Rights to
Multiple Services – Just Allow Pull Requests on
YAML files
• Different Integrations Are Inspectable
The Positives of File Based Configuration
Outweigh The Negatives of YAML
• I Just Wish Everyone Had Settled on a Different
Standard
• JSON
• TOML – Which seems like INI files with
slightly more structure

18. HAVE A ROADMAP
 What are the features that you want to add in the future? Interested contributors can only help if they
know where you want to go!
 Having a roadmap helps to make your project look active
 Recognize that most people are self interested and only contribute to things that help them directly
 Accept Pull Requests on Bug Reports
 Be Open to Ideas for the Roadmap from Contributors
 Having a roadmap makes it feel less subjective if you reject a Pull Request for a feature that seems detached from
the rest of the project.

19. CAN I SEE YOUR BADGE?
 Advertise the Health of Your Project to Potential Users and Contributors
 What do you look for when determining whether to integrate an open source library in your project?
 How active is the project.
 How many maintainers are there.
 When was the last check-in?
 How many open issues are there?
 Are there Unit Tests? Do they all pass?
 Shields.io - https://shields.io/
 Nice looking badges for all the services
 Has additional shields for services that convey more information than the default badges provided by many
services

20. ENCOURAGING INTERACTION
 Depending on how many contributors you have, you may want one or more ways of connecting
 Wiki
 Trello
 Github Issues List
 Slack
 IRC (Yes, this is still a thing)
 Discord – Not just for gaming anymore
 Have Coding or Pull Request Standards
 Or Don’t – But if you care what the code looks like, let people know ahead of time so they can conform to your
standards for a pull request

21. TALE OF TWO PROJECTS
 Humanizr - https://humanizr.net/
 .NET Library for turning text into more human and grammatically friendly
text
 Lots of Documentation
 Active GitHub Repository
 Nuget Package
 HumanizrJS - https://github.com/SamuelEnglard/Humanizer.Js
 Port of Humanizr to JavaScript
 Well… Let’s take a look

22. BRINGING IT ALL TOGETHER
 Example – TextSerializer
 https://github.com/NickSchweitzer/TextSerializer
GitHub AppVeyo
r
CodeCov
ReadTheDocs
NuGet