Creating and Maintaining an Open Source Library

Creating and Maintaining an Open Source Library

• 1.
  CREATING AND MAINTAINING AN OPENSOURCE LIBRARY MILWAUKEE CODE CAMP NOVEMBER 16TH, 2019
• 2.
  ABOUT THE PRESENTER NickSchweitzer  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!  ConcurrencyIs 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 SourceCode Control Licensing Versioning Unit Tests Code Coverage CI/CD Pipeline Package Management Documentation Maintainers
• 6.
  OPEN SOURCE TOOLING CAN BEFREE!  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 CONTROLOPTIONS 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 OVERVIEWOF 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 Publicprojects 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  WhereShould 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 TheDocs • 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 shouldbe 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  YAMLAin’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  YAMLis 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 AREYOU 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 SEEYOUR 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  Dependingon 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 TWOPROJECTS  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 ALLTOGETHER  Example – TextSerializer  https://github.com/NickSchweitzer/TextSerializer GitHub AppVeyo r CodeCov ReadTheDocs NuGet