DocOps Lab Licensing and Usage

There are a few ways to take advantage of DocOps Lab software and content.

The most common way would be as a compiled-and-packaged dependency in your own project, perhaps as a Ruby gem a Docker image. This way, you do not need to fuss over licensing at all.

If you do want to modify the code, you can fork it and make changes, then use your own modified version as a dependency in your own project. You do not need to re-share or contribute back your changes.

Modified code can be used in many ways as well, including copied and pasted snippets, or even just as inspiration for your own code. But of course you can also make a wholesale copy, modify it, and rebuild and package it for yourself, then cite that dependency in your Gemfile or Dockerfile.

The goal of any open source project should be a balance between extensibility and configurability. Most users needing to customize should be able to do so by tweaking powerful settings or an application programming interface (API) or a domain-specific language (DSL) without needing to modify the project’s source code.

Yet for users with extraordinary needs, or perhaps after the project has been abandoned, the ability to fork and modify the code is essential.

However, source code modification is not the topic of the day. In fact, it’s the opposite. We are going to review all the ways the kinds of “runtime tools” we use most in docs-as-code platforms can be modified and used without touching their source code.

Command-line interfaces can be run from any UNIX-like shell environment and manipulated with arguments, options, flags, and environment variables. This is likely the fastest way to leverage any DocOps Lab tools.

CLI commands can be scripted. You can string them together, run them conditionally, run them in loops, and so forth. Commands are simply instructions, and instructions can be concatenated into scripts.

The output can be piped to other commands for further processing.

CLIs can be used in combination with configuration, domain-specific languages, and extensions.

There are two broad categories of APIs: native and remote.

Native APIs are libraries or modules designed to be used in a given programming environment, such as Java, Python, JavaScript, or in our case mostly Ruby.

Most people in tech are more familiar with remote APIs, specifically RESTful APIs, but also GraphQL, SOAP, and other kinds.

In both cases, an API is a system that awaits input in an expected format and returns output in a documented format — usually some kind of data structure. In the case of remote APIs, the output is typically JSON delivered over HTTP.

Most command-line tools can be configured with local files that stablish a baseline of settings and behaviors. Configuration files, or “configs” , are a kind of interface, though they tend to be application-specific in structure, syntax, and nomenclature.

DocOps Lab prefers YAML-formatted configuration files, but sometimes we use INI format.

Configs are constrained by whatever the product’s developers predicted users would want to do. It often means establishing persistent preferences for the types of things CLIs and APIs allow you to indicate at runtime using arguments.

Good Configs are well documented, but truthfully configuration docs often get de-emphasized, especially in open source projects.

Domain-specific languages (DSLs) are mini programming syntaxes designed to express concepts in a particular domain, usually with modest scope.

DSLs can be their very own syntax, or they can use an existing syntax like YAML or XML in a predefined manner, expecting particular keys with a given range of values to script or configure user-defined outcomes for a given set of inputs.

Examples of DSLs you might be familiar with include:

DocOps Lab prefers to use YAML-based DSLs wherever possible, as they are easy to read and write, and widely supported.

Templates are a kind of DSL that define how input textual and variable data is to be transformed into output content.

Templates use a syntax that is interpreted by a rendering engine. This engine accepts data from an outside source (YAML or JSON or a relational database) and merges it into the template structure to produce predictable output.

Templates are often used in DocOps Lab projects to generate HTML, Markdown, AsciiDoc, YAML, or other text-based formats.

DocOps Lab prefers Liquid templates and uses an extended version of Jekyll’s Liquid 4 engine.

Forward-thinking developers instill their software with “hooks” so that downstream devs can extend the product’s behavior using its native source syntax or a DSL.

While some DSLs and templating systems are used to perform tasks the product developer predicted most users would need, extensions are for needs the developer did not anticipate or has not yet implemented.

Extensions are often packaged as plugins or modules that can be installed alongside the main product. Developers themselves often provide plugins for optional features that might not be optimal as a built-in aspect of the core product.

Other times, plugins are created by third-party developers to add functionality the original developers did not envision. These “community extensions” sometimes get merged into the official product.

Any user can develop an extension and not share it. This is common for extensions that solve an internal use case but are not designed for public consumption. A local extension can even include hard-coded data or proprietary logic that would not be appropriate for open source sharing.

Software you intend to share needs a license. What many people misunderstand is that unlicensed software you find on GitHub or elsewhere is still copyrighted, and you technically are NOT supposed to reuse it in your own projects.

Truthfully, a lot of shared code just happens to be lacking a license out of neglect, and it’s fine for you to reuse.

Most of the engineering shops I’ve worked at disallow incorporating unlicensed code even if the developer obviously intended to share it. You can always post an Issue on a project’s GitHub repo to ask the author to add a permissive license.

So we have to have a license to make it clear our code is freely copyable and reusable.

By some stroke of coincidence or culture or convention, nearly everything in our particular toolchain (meaning the applications we use to develop our own) is MIT licensed, so it makes sense to use the same license for our own code.

MIT License totally permissive; it should not trouble anyone’s manager or CTO or Legal Department, and that’s that.

There are lots of other considerations deep thinkers fuss over, but I have not found time to care much about the nuance politics of FOSS licensing.

MIT works. Apache works. BSD works. Knock yourself out.

We release some extra documentation like websites and educational materials under Creative Commons Attribution 4.0 International (CC BY 4.0) because it is similarly permissive like MIT and widely understood, and because we quite like CC and their efforts in the world of knowledge sharing.

CC BY indicates a requirement to note what changes are made if you redistribute the so-licensed content, so for stuff like Docs-as-Code School or this the main DocOpsLab.org website.

In practical terms, you can use DocOps Lab software and documentation in your own projects, whether personal or commercial, without worrying about licensing fees or restrictions. You can modify it, adapt it, and even redistribute it, and we don’t even care about credit, so long as you leave some trail back to the source.

The only real requirement is that if you do redistribute the source code itself, it must remain under the same license.