Open Tech Strategies | Blog

Open Sourcing Checklist

2023-05-19T00:00:00-04:00

Taking an existing, non-open codebase into the open is one of those tasks that seems relatively simple --- apply open source license and publish the code. In practice, however, there is some hidden complexity along the way, and many projects start out with the best of intentions but fail to complete the process.

This, of course, is why we always advise people to be open from day one.

This document is a checklist of steps you might take before you finally publish your work under open source license. Most steps are optional, but all of them have value. Think of them as best practices, not mandatory requirements. Consider each step and whether it applies to your project. Then narrow the checklist to the steps you will take. Feel free to do these in any order that makes sense to you. Good luck, and please ping us at info AT opentechstrategies.com if we can help.

This document is not an exhaustive list of concerns you should consider when open sourcing. It doesn't go into the reasons why you are considering open source (and we have found that going open without a clear goal in mind usually fails to achieve any goals at all). It doesn't include building a community or a sustainability model (open source is not, in and of itself, a business model). All of those are considerations of a much bigger picture than this checklist contemplates.

[ ] Get internal buy-in. Taking code into the open can be a big deal. It can disturb existing strategies or revenue streams. Often, publishing code is the right answer overall, but might impose tradeoffs that impact some stakeholders more than others. Some of those stakeholders might become net losers. Make sure you start the process of obtaining the necessary buy-in from internal stakeholders early. Secure support all the way up the org-chart if you can. This is the step that at first seems doable or even easy but ultimately blocks so many projects from ever going open.

[ ] Get legal buy-in. Let your counsel know you're moving in this direction. Make sure you know what their requirements are to sign off on publishing under an open source license.

[ ] Ensure regulatory compliance. Check to make sure you're square with export control regulations regarding encryption. If you're just using commonly-used open source encryption libraries, you are probably fine. Depending on what your software does, other regulatory rules might apply. Find out and get in compliance.

[ ] Check your copyrights. Ensure you have the needed permissions to release your project under open license. These permissions could come from licenses or copyright ownership. Do not assume you have the rights. Go look. Do an audit. If necessary, read up on works for hire and federal ownership of copyright.

[ ] Consider your patent portfolio. FOSS licenses sometimes include patent permissions, whether explicitly stated or implicitly granted. If you or your contributors hold patents, you should evaluate the impact of open licensing on your patent rights. You might decide your patents are best used to nurture your open source strategy. Alternatively, you might want to take steps to protect your patents.

[ ] Pick an outbound license. Usually this will be BSD, Apache, or some flavor of GPL, but there is a wide range of FOSS licenses out there for you to choose from.

[ ] Consider an inbound license. Sometimes these licenses are called "contributor license agreements". By default, a project usually takes code under an inbound license that is equal to their outbound license. If that outbound license gives the project all the rights it needs for the foreseeable future, that's good enough. If it doesn't, you might consider a contributor license agreement. Project Harmony has some sample agreements that are old but worth reading (full disclosure: James Vasile worked on that project).

[ ] Ensure license compatibility with dependencies. Two pieces of software are license compatible when they can be combined into one work and released together without violating the licenses of either of the original pieces of software. The combined work is then treated as goverend by only one of those two licenses, usually the less permissive license.

[ ] Upload your code to an online repository. This will probably be a git repository hosted on GitHub, LibreHQ, or a GitLab instance. Do not make it public it yet.

[ ] Add a README.md file. Place it in the root directory of your repository. It should specify the name of the software and describe what it does in lay terms. Include contact information, directions to your mailing list or Zulip/Slack /Discord instance, and your general level of willingness to accept public participation. Provide basic instructions for installation or refer readers to online documentation.

[ ] Test installation. Give repo access to a new user or developer who has never installed your software before. Have them follow your instructions. If they got a running installation, good. If not, fix your instructions before you publish.

[ ] Fix your test suite. Ensure your tests pass. Sideline (e.g. mark "expected fail") those that don't. New users will often run tests to make sure their install worked. If the tests fail, it will be difficult for them to know whether that is because the install failed or because that test stopped passing and nobody cared.

[ ] Add a LICENSE or COPYING file.

[ ] Add a CONTRIBUTING file. This file tells people how to contribute.

[ ] Prepare for public participation. Pay particular attention to your planned cadence of replies to incoming interest. Your approach to inbound messages will, of course, depends on your community strategy, which is beyond the scope of this checklist (see our Archetypes Analysis and Producing OSS for starting points). Document that approach in your README or CONTRIBUTING file so people can form expectations about how quickly you will respond to issues and PRs. See

[ ] Add issue templates. These can help guide public participation. Give people some hints about where discussion of issues happens. Typically, public projects default to the issue tracker, but some prefer the project's mailing list or forum.

[ ] Examine ownership of your repository. Make sure multiple people have authority and actual ability to administer the repository.

[ ] Squash history. Does your repository contain sensitive information or secrets? Has it ever? When repositories are private, people tend to be less guarded about what they check in to the repo. Problematic content includes secrets and PII but also might include commit messages containing profanity or even defamatory content. It is not practical for most projects to examine all their history, so many delete, edit, or squash history before going public.

[ ] Remove secrets. Ensure there are no API keys or passwords or other sensitive information in the remaining codebase.

[ ] Publish documentation. Centralize it into an accessible location under open source or creative commons license. Documentation should be open to change requests. Track down the design and usage documentation that may currently reside in various internal places and make them public. Collect the implicit learnings of your team, and write them down so people without your experience can productively approach the software.

Remember, this checklist is a general list of tasks, some of which might not apply to you. Adapt it to your specific needs and legal requirements. Work with your lawyer and your open source advisor to reduce this to the list that works for you and your product.

Thanks to Karl Fogel, Frank Duncan, and Jesse Bickel for reading early drafts of this checklist.

Moving Repositories Between Project Hosting Platforms

2023-01-10T21:52:00-05:00

No matter how tightly developers are committed to their current project hosting provider (GitHub, GitLab, GNU Savannah, or whatever), new ones will come along over time. The history of web services is replete with turnover, and project hosting forges all follow the inevitable trend. But the cost of migration is formidable: It's quite easy to setup a new project host like GitLab, but how do you move the whole structure of your team’s code, branches, comments, issues, and merge requests into their new home?

Software Heritage, a non-profit with the mission of archiving free software code, faced this daunting challenge when they decided to move from Phabricator to the more vibrant GitLab. For a while, a lot of free and open source projects had found Phabricator appealing, but the forge had been gradually declining and officially ceased development in 2021.

At OTS, we developed an open source tool and framework to support migrating to a new project hosting platform. We used it to move all of Software Heritage's projects from Phabricator to GitLab, but the framework is robust enough to support migrations between almost any project hosts.

The tool is called Forgerie. Its goal is to automate the migration of projects from one hosting system to another. Forgerie is extendable to any source and destination. It translates input from a project hosting platform into a richly-featured internal format, then exports from that format to the destination platform.

This is the same method used by many tools that perform n-to-n migrations. For instance, the health care field contains many incompatible electronic record systems, so migration tools usually create an intermediate format to cut down on the number of necessary format conversions.

OTS continues to work on Forgerie as part of its offering of migration services to clients. If you would like to use Forgerie, please grab it from Forgerie's GitLab page or contact us if you would like help with a migration.

The rest of this post offers some technical background on Forgerie. It should be of interest to anybody solving similar project hosting problems or, more generally, to anybody working on moving structured data into a new data store. Many migration projects fall into the traditional category of Extract, Transform, Load (ETL), but the richness of data stores today stretches the category into new realms.

Forgerie

The Forgerie code was initiated by OTS developer Frank Duncan and released under the GNU Affero General Public License v3.0. This post delves into the project goals along with suggestions for the future of this project. We'll look at the difficulties posed by this major migration project and how we handled them. This story may offer lessons and tips to people dealing with all kinds of data migration.

If you have used a project hosting system, you might well be imagining the massive requirements for even such a limited project. Code in a forge exists in many branches, each created by multiple commits and enhanced by merges. Numerous issues (change requests) have been posted by different users, along with comments that refer to the issues by number. Commit messages also link and refer to the numbers of issues and branches.

The need for a general project hosting migration tool

Tools for importing projects exist for various project hosting platforms, but they are limited. GitLab does a pretty good job importing a repository from GitHub, and GitHub from GitLab, and both allow the uploading of a private repository. Later in this article we’ll examine one particular limitation of all these import tools: handling multiple contributors.

To automate the migration from Phabricator to GitLab, Software Heritage contracted with Open Tech Strategies (OTS), a free and open source software consulting firm. Preliminary research turned up a few tools claiming to perform the migration, but none of them did a complete job. And each migration tool works only with one particular forge as input and another as destination. OTS decided to design its new tool as a general converter that could be adapted to any source and target repositories.

Migration thus requires the automated tool to reproduce, on the target forge, all the projects, branches, commits, merge requests, merges issues, comments, and users recorded in the source repository. If possible, contributors should be associated with their contributions.

OTS chose to create Forgerie in Common Lisp, which seems like an odd choice in the 2020s. But Common Lisp is well-maintained and robust. Its big advantage for the Forgerie project was that Lisp makes database-to-dictionary conversions easy. Because Phabricator stores data in a relational database, database-to-dictionary conversions were the central task in automating the migration.

The Forgerie project has three subdirectories: a set of core files used by all migrations, egress files for Phabricator, and ingress files for GitLab. This design leaves room for future developers to extend the project by adding more ingress and egress options. In order to go from Phabricator to GitHub, for instance, a maintainer can reuse the existing core and Phabricator directories.

Impedance mismatches create challenges

All forges offer basic version control features, along with communication and management tools such as issues. But each forge is also unique. In this case, Duncan had to decide how best toaccommodate features that differ or are missing in the target GitLab platform.

The biggest challenge Duncan faced is that GitLab maps projects to repositories on a one-to-one basis, whereas Phabricator treats a project as a higher-order concept. A project in Phabricator can contain multiple repositories, and a repository can be part of many projects. Phabricator also supports multiple version control tools (Git, Mercurial, etc.). Making Forgerie flexible enough to smooth over these types of differences in data structure was a key goal.

The different approaches to projects introduced several complications. First, Duncan had to make sure that each message and ticket pointed to the right GitLab project.

Merge requests were the hardest elements to migrate, because in Phabricator a changeset can span multiple repositories. The requirement that Duncan had to implement was to preserve the sequence of events in the original forge strictly, so that issue 43 in the old forge remains issue 43 in the new forge. That way, any email message or comment referring to the issue still refers to the right one.

Lots of details had to be tidied up. For instance, Phabricator has its own markup language to add rich text to comments and issues. This language had to be converted to Markdown to store the comments in GitLab.

The question of multiple contributors

When there are many people to credit for their contributions, the import tool has a tough nut to crack. Awarding credit properly is crucial because many contributors rest their reputations on the record provided by their contributions. Statistics about the number of commits they made, the “stars” they got, etc. undergird their strategies for employment and promotions. Losing that information would also hurt the project by making it hard to trace changes back to the responsible person.

On the other hand, security concerns preclude allowing someone to import material and attribute it to somebody else.

GitLab solves this problem if the input repository is set up right: The person doing the import needs master or admin access and has to map contributors from the input repository to the destination respository. If access rights don't allow the import to add material to a contributor's repository, GitLab's import can accurately attribute issues to the contributor, but not commits.

Forgerie goes farther in preserving the provenance of contributors: It keeps track of Phabricator users and creates a user in GitLab for each user recorded in the Phabricator repository. The Software Heritage project did not present difficulties because no contributor had an account in GitLab. To be precise, the email address that identified each Phabrictor contributor didn’t already exist for any GitLab contributor. If GitLab had an account with the same email address as an account being imported, the system would have issued an error and prevented Forgerie from importing the contributor’s commits.

A few implementation details

Forgerie carries out a migration by creating a log of everything that happened in the source repository, and replaying the log in the target forge. Phabricator uses a classic LAMP stack, storing all repository information into a MySQL database. Forgerie queries this database to retrieve each item in order, then invokes the GitLab API to create the item there.

The GitLab API is relatively slow for those particular types of request, requiring one or two seconds for each request, and repositories can contain tens of thousands of items when you count all the merges, comments, etc. So you can expect a migration to take 24 hours or more.

Long runs call for checkpoints and restarts. When Duncan designed the simple version of Forgerie for him to run just once, he figured he could just restart the run if it failed. Later he realized that restarting after 23 hours became unacceptable.

The log solves this problem through a kind of simple transaction. You can conceive of the migration as moving through three stages (Figure 1). In the first stage, items are in the old platform but not the log. In the second stage, Forgerie adds the items to the log. In the third stage, items are safely loaded into the destination platform and can be removed from the log. Should the job fail, the user can restart it from the beginning of the log.

Figure 1: Logging items as they move from source to destination platform.

A classic issue with transactions arises with a log: Suppose an item has just entered the target forge but Forgerie did not have a chance to remove the item from the log before a failure. The item exists in both the target repository and the log, so when Forgerie starts up again, the item will be added a second time to the repository. Forgerie developers do not have to worry about this happening because the insertions are idempotent. The second insertion overwrites the first with no corruption of information.

Assessing the Forgerie project

The Forgerie code base is surprisingly small–a total of 2,726 lines, divided as follows:

Core (shared) code: 350 lines
Phabricator-specific code: 1,233 lines
GitLab-specific code: 1,143 lines

No platform lives forever. Amazing as the capabilities of GitHub and GitLab are—and they continue to evolve—there will come a time when developers decide they have to pick up and move their code to some glorious new way of working. Forgerie tries to make migration as painless as possible.

Thanks to Andy Oram for assistance drafting this post, to Jim McGowan for making the diagrams, and to Antoine R. Dumont of Software Heritage for contributing technical improvements to the Forgerie project.

Need help migrating off Phabricator?

2022-02-17T14:09:00-05:00

Open Tech Strategies can help you migrate off of Phabricator now that it has reached end-of-life. We developed Forgerie, an open source tool that aids in migration between code forges. Forgerie extracts data from your Phabricator instance and injects it into a GitLab instance. It can also help move repositories to a GitHub account.

Using Forgerie is a process. It requires setting parameters, running the tool, examining the results, tweaking the parameters, and re-running until the result meets your needs. Our team can help you with this process. We can move you to your own GitLab instance, host an instance for you, or get you migrated to GitLab.com or GitHub.

We'd love to help you transition from Phabricator. Drop us a line at info AT opentechstrategies.com and we'll get you safely to your new home.

Open Source Readiness Models

2020-09-17T19:54:00-04:00

(This is the seventh post in our Open Source At Large series.)

Open source is a powerful tool that offers great benefits to organizations that make, maintain, or deploy software. Most teams know they need open source capabilities. The hard part is finding a focus around adding skills. In most cases, the most important consideration is building capability to know how and when to use FOSS strategies.

FOSS is all about execution. Reaping the benefits of open source investment requires nailing a series of difficult steps ranging from designing an initial strategy to building an appropriate community to leveraging the resulting dynamics for strategic advantage. Many organizations are not prepared to travel that path and reap those rewards at scale. At OTS, we talk about that level of capability as organizational readiness, and we describe the journey to mastery as one of gaining capability.

To do that, we might locate a team in a readiness model. This clarifies where they are and also suggests next steps and likely results. Often, organizations use these models to identify areas for potential growth. We find the models are most useful for firms early in their open source journey, and this post focuses on those early stages.

There are several readiness models. OTS has for many years described climbing the readiness ladder (in various publications). Microsoft's Jeff McAffer sees common patterns in an engagement model. GitHub also sketched maturity model as the start of a discussion on readiness. Similarly, Wikipedia reproduces an interesting model from Qalipso. There are a number of such models, and it is often worth considering more than one when examining an organization. Of the published models, we like McAffer's in particular because it includes strategic components, accounts for realistic failure modes, and understands that open source readiness will be unevenly distributed in large organizations.

On many teams, initial open source capabilities might be nascent. Most team members have not had significant (or perhaps even any) experience using open source strategies to create value. The team works in an environment where FOSS investment is rare, and many do not see much reason to change that. That lack of knowledge might translate in some quarters into hostility toward FOSS. People will say ``It can never work here'' even as open source slowly seeps into more and more of the technology around them.

At this stage, FOSS strategies can be difficult to execute. Internal political risks might be high. Policies might explicitly forbid engaging FOSS. Staff doesn't know how to begin to work with external open source teams. Many people will lack even a basic understanding of what it means to do open source work. Efforts to work in an open source mode are likely to fail in ways that reinforce the belief that open source is not worth further consideration.

Many factors might move an organization from hostility toward tolerating open source, but movement usually comes from external pressure, changing environments, and staff turnover. Conditions around the organization begin to change, and the costs and risks of refusing to engage start to rise.

Those costs might include the pain of maintaining internal forks of external open source projects (or, more precisely, the pain of not maintaining all those forks). Similarly, the benefits of making minor open source investments start to become clear, even if only from watching others make those investments and reap the benefits while your organization loses ground.

However organizations begin to come around, tolerating open source is all about experimentation. Firms usually don't think of it in those terms. They are making small concessions to necessity. They are seizing unique, one-off advantages. Most don't think of those small projects as the future direction of the company. They should consider the possibility, though. Sometimes, explicitly labeling such experiments as learning exercises and skill-building allows an organization to maximize the value of their experimental investment. It prioritizes reflective analysis and learning. It gives permission to fail. Those can be useful to companies seeking adaptability. When considering McAffer's model, we might relabel his "tolerance" phase as "experimentation".

Experiments come in many forms, but the most common first experiment is using some outside open source code and engaging the open source project. That might involve filing bug reports, offering a contribution, or merely participating in project mailing lists and forums. These are all relatively low-risk ways to begin connecting an organization to outside FOSS projects.

The experimentation phase is usually a skill-building and knowledge-gaining phase because it exercises the skills that cause an organization to shift from merely tolerating open source to trying to harness it. Having those skills provides the vision that starts to shift attitudes.

The problem that arises as companies start to embrace FOSS is that they lack the infrastructure to succeed at it across the entire organization. They are missing policies, auditing, skills, culture, and experience. This is a pivotal, risky moment. A large number of teams will still be in the denial phase. Efforts to move internal culture toward FOSS will be perceived by some as a pointless shift toward the latest buzzword. Those experimental skills will be unevenly distributed internally. Many new open source projects will fail, and this will convince some that FOSS is a failure. Some might even sabotage FOSS projects.

McAffer sees this phase as one of hype, and perhaps that's because it's also when an organization embraces open source without quite being ready to execute. Firms in this phase tend to engage FOSS in shallow, unsophisticated ways simply because they don't yet have the experience to make better strategic use of open source opportunities. The way to move past this stage is not to reduce the hype (though that might help) but rather to increase readiness.

Managers at this stage -- especially middle managers -- need guidance on using FOSS as a strategic component and on managing teams with more external deliverables. Developers need technical infrastructure, easy-to-follow licensing policies, and permission to engage externally. Perhaps more importantly, they need to develop new habits of working in the open and sharing even early, rough versions of their work. Beyond just technical teams, Human Resources needs hiring and compensation guidance as both skills and performance evaluation criteria shift. Providing all of those pieces is the process of gaining proficiency. Adding skills, process, and policy is how that happens, and it requires management approval and resources. Companies that don't provide this support from fairly high in the org chart tend to plateau at this level of readiness.

All of the above describes a path from the very beginning toward eventual mastery of open source. We think of readiness in terms of skills and capabilities, but the truth is that doing open source well is primarily a cultural shift. Organizations using open source fluently quickly find that the open approach becomes their default process. That culture shift will be the topic of a future post. For now, though, where is your organization on the path toward readiness? What are the steps you can take to help prepare for an increasingly open source tech landscape?

Keep Your Friends Close

2019-11-21T18:07:00-05:00

(This is the sixth post in our Open Source At Large series.)

One of the insider secrets of free and open source software (FOSS) is that most of the rules a project uses on a day-to-day basis are not found in the software’s license. There are contribution guidelines, which are enforced by the project only taking contributions that meet them. There are codes of conduct, which are a condition of community participation. There are endorsements, official membership, a voice in setting the project roadmap, and all kinds of other benefits that attach to varying types of community participation. In each case, entirely external to the license, there are official rules and unwritten norms that govern how participants gain the benefits of joining the civic life of a project.

If you were to make an ecosystem map of an open source project, you might place the project in the middle of the page and then depict scale of involvement as distance from that center. The closer to the center a participant sits, the more influence the project has on them; the further from the center, the less sway the project has.

At the center is the project itself: its core developers and the people who have made commitments that affect the project’s outputs and actions. A project has a lot of visibility into how these participants act because tight, highly-connected cooperation is beneficial for everyone, and so participants are motivated to act in ways that avoid damaging that cooperation. This mechanism is so natural that most projects do not often think of it as something they could expand intentionally. But sometimes projects do exactly that: they figure out ways to deliberately widen their sphere of influence.

For example, Joomla, maintains a directory of third party extensions. It is the way most users discover Joomla extensions. For many businesses based on providing Joomla extensions, absence from that directory is akin to not existing at all. When the Joomla project decided to tighten license compliance among its extension developer community, they didn’t ask their lawyer to run around issuing threats. They simply explained that any project that wanted to appear in that directory must abide by community rules, https://docs.joomla.org/Extensions_and_GPL. Extension developers came into line.

A similar example can be seen in the Guidelines for Commercial Entities at the Arches Project. A glance over the guidelines will show the kinds of real-world problems they were developed to address. Only those who agree to the guidelines are listed in the official directory of Arches service providers.

Of course, being in some kind of project-endorsed directory is just one type of gateway. Another is participation in the project at all, that is, the ability to take part in project discussions, to vote (when there are decisions made by vote), and to have one’s contributions evaluated and accepted by the project with full attribution. Getting contributions accepted into the core project on a regular basis is important for those whose businesses depend on the project. If they can’t get their bugfixes and new features accepted upstream, then they may be forced to maintain their own divergent version (the term of art is “vendor branch”) indefinitely — a situation whose technical and organizational costs only get worse over time.

The right techniques will differ from project to project, because they must be based on the particular project’s history (as in the examples above). But the general reason these techniques work is that the non-code parts of a project are valuable in their own right. Those parts are not covered by the code’s license, but rather by the project’s norms and rules. Crucially, these parts cannot be replicated: unlike the code, you can’t make a copy of a community, or of a developer’s attention, or of an endorsement’s value. Equally crucially, none of them can be demanded by bad actors. The benefits of participation flow naturally to community members in good standing and it is equally natural to deny them to people and firms that refuse to align themselves with the community ethos. Creating structures that allow projects to control access to community benefits is a powerful way to enforce norms.

Using community participation as the mechanism for promulgating norms has its limits. Some participants stay far enough from the center of the project that they are effectively immune to community inducements. (Fortunately, projects have other mechanisms available to influence them, and we will cover some of those in a future post.) But in most cases, organizations that have a core reliance on the code will find multiple reasons to stay in good standing with the community, and this means the project has a chance to influence how those organizations behave. Spotting these leverage points takes experience as well as an understanding of project goals and positioning. Projects that want to wield influence over their ecosystem — whether for strategic or ethical ends — should actively look for ways to provide value backed by network effects, until the case for participation is overwhelming.

Thanks to Microsoft for sponsoring theOpen Source At Largeblog series.

Spot The Pattern: Commoditization

2019-10-02T15:28:00-04:00

(This is the fifth post in our Open Source At Large series.)

Last week, I spoke with the CEO of a company that makes a proprietary, category-leading workflow product. He asked me "what should we open source and when?"

This is one of the most common questions we get. There is no easy, standard answer to this question, but I usually start by looking for features of the ecosystem that either are or could be commoditized.

A commodity is something that is the same no matter who makes it. Gasoline is a commodity. Customers don't really care where they buy gas. They want it cheap and reliable, but the gas itself should be the same stuff regardless of which oil company refines it and pumps it into your car.

In practice, of course, gas from different companies is not identical. Some places enhance it with detergents, mix it with ethanol, or add stabilizers. But for the most part, consumers ignore these small differences. You put it in your car and it works. People pick gas stations based on price and convenience.

It's hard to charge a premium for a commoditized good. People are not willing to pay extra for a product if they can get the equivalent for less elsewhere. As a result, gas stations compete on price. This squeezes margins, and so in the end they make their money on the convenience store, just like movie theaters do with popcorn.

Open source software businesses are often in the same position. There's a core offering that is, to put it bluntly, boring. Anybody could offer this boring core without innovating. You cannot be in the market without matching the core's offerings, and customers want standard interfaces these days, so there's not much opportunity to differentiate on the basic core offering.

Database servers follow this model. From a business perspective, storing rows of data is not interesting. Everybody can do it, and nobody really does it much better than anybody else. There are performance improvements at the margins, and we can build interesting services on top of storing information, but basic data storage and retrieval is just facilities maintenance, not the thing your customers choose you for.

Of course, not all data storage is basic. You can store things faster or in ways that make access easier. You can stack data vertically instead of horizontally. You can keep all the data in memory, duplicate it across multiple servers, or sync with client-side storage. These are features that can set one product apart from another. You might be able to charge a premium for them. None of them, though, is actually the boring, basic task of putting data on a disk and making sure you can find it later.

For a business that manages data but can't find competitive advantage on storing it, the database is a cost. It's not worth spending a lot of money to develop or acquire a database that improves on the standard set of features because there's just not much improvement to be had. Best to source those features as cheaply as possible.

Of course, the same logic applies to everybody else in your industry. We're all trying to get the boring stuff done as cheaply as possible. This is where open source cooperation comes in. We can't compete on those features, so there's no point being competitive about it. We use open source to get together and collaborate with all the other folks who want rock-solid databases. Open source lets us do this even if we're in competition on a range of other fronts.

We see this pattern a lot in free and open source software. Product categories go open source, then contract, then perhaps expand when somebody figures out the next frontier of differentiation. Most recently, we've seen this effect around web rendering engines. Every browser's goal is to depict HTML in standard ways. Aside from being at Google's mercy, there's little reason for most companies to make their own rendering engine when there's a pretty good one that is open for the taking.

Spotting this pattern early is a crucial step in knowing what to open source and when. You can lead or let somebody else lead -- either might be strategically useful, but spotting the pattern lets you choose which position to take.

Sometimes it makes sense to open source what you have mainly as a signal to others that an area is becoming commoditized and so they should open source their stuff too. That is, you don't necessarily have to be aiming for a dominant position in a new open source area -- in fact, you often don't have to decide that in advance. Instead, you open source because an area is about to become commoditized, and the earlier you shift your investments, the better positioned you will be get the type of influence that serves your needs in the inevitable post-commoditization universe. (For more about the various forms that influence can take, see Open Source Archetypes.)

Once you start looking for the commoditization pattern, you see it all over the open source world. It is a common tool for understanding the strategic position of all kinds of products. In addition to the basic pattern, there are two more big concepts around commoditization worth considering: the cyclical nature of commoditization and the factors that allow resisting that cycle. We'll cover those in future posts.

Thanks to Microsoft for sponsoring the Open Source At Large blog series.

Ecosystem Mapping

2019-06-24T19:39:00-04:00

(This is the fourth post in our Open Source At Large series.)

All the power of open source comes from throwing in with your neighbors, even the neighbors you don't like very much. For most projects, the main reason to get involved in open source is to create productive relations with as many participants as possible, including rivals. Doing this well requires understanding who is in your ecosystem and how they relate to each other.

Whenever a team comes together to plan their open source strategy, they need a way to gather that understanding. They want to pool their knowledge and get everybody working from the same set of facts. The best tool we've found for this is ecosystem mapping.

There are many ways to visualize groups of stakeholders. We generally recommend starting with who and going from there to what. You can capture users, contributors, service and support providers, partners, funders, investors, deployers, integrators, and competing or adjacent efforts. Grab anything important to the questions directly in front of you, and don't worry about being complete.

Ecosystem maps are lightweight. They should be messy, quick, and replaced often. The best way to make one is to hand-draw it on a large piece of paper or on a whiteboard, ideally as a group exercise. Snap a pic for future reference, but don't bother taking the time to redraw them neatly. In a fast-moving project, the terrain these maps describe will shift often. And the reasons why you might draw a map will change even faster. It is not unusual to make several different maps of the same ecosystem in an afternoon.

Here is a simplified version of an ecosystem map drawn by the Arches Project. (We reproduced it in Dia for this article, but normally we wouldn't bother to digitize a map, beyond photographing the whiteboard or paper it was drawn on.)

Notice how the diagram is primarily designed to highlight geography but also uses color and shape to distinguish between different types of participants.

The day the team drew this map, we wanted to understand where the project was succeeding geographically and how to support participants spreading the project into new communities. We suspected that having a set of committed users and service providers doing custom deploys were both important, so we mapped it to kick off a group discussion. As we talked through planning, we referred to the map, adjusted it at times and later even drew another map with a new focus. The diagram was a guide for conversation and let everybody agree on parameters quickly.

This is a map drawn of the Tor Project by Dlshad Othman:

This map is more centered on interactions with the Tor Project. It doesn't mention geography at all, and it uses enclosing shapes to group types of participants in a venn-diagram. It shows roles and relationships with a heavy focus on the project itself.

There is no one right way to draw an ecosystem map. There are, however, some signs that your map is not set up to capture relationship complexity:

It is shaped like a star, with all your connections coming back to one central entity.
It is more of a cloud than a map. If the map doesn't depict relationships between entities, it's not doing its job.
It tries to answer too many questions at once. Maps are usually single-use snapshots designed to highlight one aspect of your ecosystem. As two-dimensional representations made quickly with a limited palette of colors and symbols, these maps can show complex relationships, but not easily accommodate high-cardinality data views.

That said, do whatever works for your purpose! Experiment with different techniques, and draw maps that highlight different types of information. If you make a map using some of these techniques, let us know in the comments. We’d love to see pictures of maps that might turn into future examples as we continue to help people apply this approach to crafting open source strategy.

Thanks to Microsoft for sponsoring the Open Source At Large blog series, and also to Dlshad Othman and the Arches Project for kindly letting us use their maps as examples.

Open Source Goal Setting

2019-05-29T03:41:00-04:00

(This is the third post in our Open Source At Large series.)

Open source is a strategic tool, not an end in itself. It is the
stone in your stone soup. You don't eat it — it's
just the invitation.

You reach for open source to create effects that will support your
broader strategy. We've talked to dozens of clients about why they
invest in open source, and the reasons tend to be fundamental and
long-term: to achieve a cultural change in their technical
organization, to influence a market's direction, to recast
relationships with partners, etc. Direct revenue is rarely the main
goal of open source investment, even for for-profit businesses.
Rather, open source is used to create an environment in which
revenue-generating activities can thrive.

Below is a checklist, or rather a provocation list. It's meant to

help you answer the question "What effects do we most want from our open source investment?"

Treat this list as a menu, not a buffet. Pick three items and make them your high priority targets. Focus on effects that connect best to your strategy, and, ultimately, to your organization's mission. You need to know where you want to go before you can chart a course to get there. We've broken the goals into three categories, but you can mix and match across or within categories as you please.

Development and Collaboration

Expand or amplify developer base
Gain market insight
Gain or maintain insight in a particular technical domain
Influence a technical domain
Create a framework for partner collaboration
Lead a standardization effort
Disrupt an incumbent, hold off insurgents

External Positioning

Ease customer fears of vendor lock-in
Deepen engagement with users, create more paths for engagement
Transparency for customers and partners
Establish a basis for product reputation
Organizational branding and credibility
Product branding and credibility

Internal or Structural Change

Improve internal collaboration (cross-individual or cross-departmental)
Create opportunities for internal mobility
Expand or reshape hiring pool, expedite recruiting
Improve morale and retention
Create flow-paths for bottom-up innovation
Improve and maintain open source capabilities (technical and social)

Again, we emphasize the importance of picking just a few.
Winnowing down to just the most important goals is usually
illuminating, because it forces your organization to articulate what
it's really after. Every item on the menu might look inviting, and
any of them can be pursued opportunistically, but a strategy that
tries to chase all these goals at once will go nowhere.

If you have goals for open source investment that don't appear on
this list, we'd love to hear them. The list was built up over years
of experience, and we generally find that we can map from it to the
specifics of a particular client's or project's
needs — most open source dreams appear somewhere on
this list. But that doesn't mean we can't be surprised, and we're
always happy when we are.

Thanks to Microsoft for sponsoring theOpen Source At Largeblog series.

What Is Open Source Strategy?

2019-05-15T09:00:00-04:00

(This is the second post in our Open Source At Large series.)

There is a lot of documentation out there on how to do open source well at the project level. Historically, many projects have been started by developers, often on their own initiative, and the first non-technical questions they faced tended to be about project coordination (like "What collaboration tools shall we use?" or "What will our code review practices be?") and about community management (like "How do we decide who has commit access?" and "How do we integrate newcomers smoothly?"). Because developers hate to solve the same problems over and over, there is a wealth of detailed and varied material addressing those sorts of questions (we've even written some ourselves, but it's just a drop in the bucket of what's available). Taken together, this literature thoroughly answers the question "How do we execute the best tactics for developing open source software?"

But there isn't yet a lot of material on open source strategic thinking. Indeed, it's traditionally so under-discussed that often when we talk about it people think that we're talking about the nuts-and-bolts of how to run projects, rather than the broader question of how an organization uses open source to further its mission.

This blog series is about open source strategic thinking, so the first thing we want to do is define what that is. It overlaps with tactics, of course. For example, the tactical question "How do we integrate newcomers smoothly?" unfolds to become the strategic question "What are the long-term returns we want from engaging with others, who are those others, and what kinds of investments should we make in order to achieve those returns?"

Let's run with that example for a moment. It's deceptively easy, with one's overworked-developer hat on, to think that the answer is obvious: "Oh, we want to bring in others because then they'll contribute code and bugfixes and documentation to the project, thus lowering the costs of development for everyone else." But with one's strategic-thinker hat on, the question starts to look more complex — its many possible, non-mutually-exclusive answers each affect the shape of the investment.

If one of the ways the open source project serves your goals is by providing a channel for closer technical cooperation with customers and potential customers, then perhaps your investment in engaging participants should emphasize fast response times in discussion and deliberate probes to uncover usage scenarios. On the other hand, if the point is to disrupt a competitor's proprietary product in the marketplace, then it might make more sense to invest heavily in ease of deployment, including fast processing of the relevant bug fixes and documentation contributions. One thing is certain: you cannot make every investment at once. All human endeavors are resource-constrained, and software projects are certainly no exception. One does not have a choice about prioritizing; one merely has a choice about whether to do it purposefully — strategically — or accidentally.

Please do not place too much weight on that one example, in any case. While investment in new participants is an important component of open source strategy, it is not the only component. If we were to make a high-level list of possible strategic concerns, it might look like this:

How open source supports your mission or goal.
How it affects your relationship with competitors and their products.
How it affects your relationship with customers.
How it affects the internal structure of your organization.
How open source allows you to draw in partners; how it affects where those partners come from; how it defines your relationship with those partners and their relationships with each other. (Project governance is a subset of this, but typically is not the most important subset.)
What types of investments you need to make to shape the above relationships in ways that serve your goals.
How you sustain your open source efforts over time. (A project's sustainability model(s) is not the same as any one of its participants' business models. An open source project that aims to create a diverse ecosystem of lightly-involved support vendors will have a very different sustainability model from a project that supplies a key piece of infrastructure needed by a few large corporations.)
What you can do as an open source actor that your proprietary competitors cannot.
What collaborative or market opportunities does being open source enable?

These concepts are not just for executives and managers, by the way. Developers benefit from strategic awareness, and of course can help support a strategy most effectively if they know about it. Our target audience for these posts is developers who want to think strategically, as much as it is managers and organization leaders.

In order to do strategic planning around products and projects, we have found a common set of base information and exercises to be useful: explicit goal-setting; mapping the ecosystem that surrounds the project; identifying business models (before identifying sustainability models); understanding the cyclical way in which open source commoditizes product categories and what that implies for the particular product and category in question; how an open source project relates to the procurement and deployment habits of its intended audience; and making choices in the inevitable trade-off between control and reach.

We will discuss each of these in future posts in this series. The point of this post is simply to say that strategy is a thing, and that it is separate from community management, collaboration tools, and everything else that makes things run at the project level. To use open source to meet your goals, it is necessary to structure your open source engagement in ways that align with those goals — and this is fundamentally a strategic question that won't be easily answered from within the confines of day-to-day technical development.

Thanks to Microsoft for sponsoring the Open Source At Large blog series, and thanks toJosh Gayfor sending us copyedits on this post.

Announcing a New Series: Open Source At Large

2019-05-14T04:20:00-04:00

Open Tech Strategies has a dual mission. Day to day, we help our clients understand how open source approaches fit into their strategic goals, and we help them implement those approaches. But over the long term, we also try to act at the ecosystem level when possible. The more organizations invest thoughtfully in open source, the better off open source as a whole is — and the more organizations will want to try it, in a virtuous circle.

For years we've been digging into the details of our clients' operations, customer bases, and markets in order to help them recognize and act on specific open source opportunities. While this work is tailored to each client, we are always looking for ways to publish what we learn so it can benefit a wider audience. Our work with Mozilla on Open Source Archetypes and with the World Bank on their investment strategy for the GeoNode project are two examples. We've heard from open source practitioners across the field that these materials have been helpful to them (and we've received useful criticism and feedback — the sincerest form of flattery). Perhaps most gratifyingly, we've heard from internal open source champions at organizations that are still finding their way toward deeper open source engagement, telling us that having strategy-level materials to refer to helps them make their case.

Now we have a chance to do that kind of public analysis in a more regular and focused way. Starting this week, OTS will publish a series of blog posts focused on strategic concerns in open source. The series is kindly sponsored by Microsoft, whose request to us was essentially "help organizations get better at open source" (not a direct quote, but a decent summary). They were clear about the series being independent: they did not want editorial control, and specifically did not want to be involved in any pre-approval before a post is published. It goes without saying — but we'll say it anyway, just to be explicit — that the views we express in the series may or may not be shared by Microsoft: please blame us, not them.

We'll focus on the kinds of analysis we do when we advise clients: how to identify opportunities, how to make decisions about prioritizing and shaping open source investments, how to integrate open source methods into one's business models and goals, monitoring and improving open source project health, and more. Our clients will recognize some of this material — our advice tends to be consistent over time — but much of it will be ideas we have not discussed widely before. We look forward both to offering strategic analysis to newcomers to open source and to engaging our colleagues in the open source field in a wide-ranging discussion.

Our first substantive post discussing "What Is Open Source Strategic Thinking?" is up. Watch this space for more!

Be Open From Day One, Not Day N.

2018-09-05T16:40:00-04:00

Note: This is an updated version of an article I first wrote in 2011. The original site went offline for a while, and although it was later restored, thanks to heroic efforts by Philip Ashlock, I felt the article needed a new home, and wanted a chance to update it anyway. This version also incorporates some suggestions from V. David Zvenyach.

Over the years we've watched software projects of all sizes make the transition from closed-source to open source. The lesson we consistently draw from them is this:

If you're running a software project and you plan to make it open source eventually, then just make it open source from the beginning of development.

Waiting will only create more work.

The longer a project is run in a closed-source mode, the harder it will be to open source later.

(Note that being open source from the start doesn't force you to immediately take on the extra responsibility of community management. People often think that “open source” means “strangers distracting my programmers with questions”, but that's optional — it's something you might do down the road, if and when it makes sense for your project. It's under your control. )

Projects seem to follow the rule pretty convincingly: the longer they run closed-source, the more difficult they are to open up later. Other people we've talked to have noticed the pattern too.

Why does it seem to hold so consistently?

I think there's one underlying cause:

At each step in a project, programmers face a choice: to do that step in a manner compatible with the future open-sourcing, or do it in a manner not compatible with the future open-sourcing. Each time they choose the latter, the project gets just a little bit harder to open source.

The crucial thing is, you can't help choosing the latter occasionally — all the pressures of development propel you that way. It's very difficult to give a future event the same present-day consequences as, say, fixing the incoming bugs reported by the testers, or finishing that feature the customer just added to the spec. Also, programmers struggling to stay on budget will inevitably cut corners here and there (that is, they will incur technical debt), with the intention of cleaning things up later.

Thus when it's time to open source, you will suddenly find:

Customer-specific configurations and passwords checked into the code repository;
Sample data constructed from live (and confidential) information;
Bug reports containing sensitive information that cannot be made public;
Comments in the code expressing perhaps overly-honest reactions to the customer's latest urgent request;
Archives of correspondence among the developer team, in which useful technical information is interleaved with personal opinions not intended for strangers;
Licensing issues with dependency libraries whose conditions might have been fine for internal deployment (or not even that), but aren't compatible with open source distribution;
Documentation written in the wrong format (e.g., that proprietary internal wiki your department uses), with no easy translation tool available to get it into formats appropriate for public distribution;
Non-portable build dependencies that only become apparent when you try to move the software out of your internal build environment;
Modularity violations that everyone knows need cleaning up, but that there just hasn't been time to take care of yet;
Need I go on? Do some of these sound familiar?

The problem isn't just the work of doing the cleanups; it's the extra decision-making they require. For example, if sensitive material was checked into the code repository in the past, your team now faces a choice between cleaning it out of the historical revisions entirely, so you can open source the entire (sanitized) history, or just cleaning up the latest revision and open-sourcing from that (sometimes called a “top-skim”). Neither method is wrong or right — and that's the problem: now you've got one more discussion to have and one more decision to make. In some projects, that decision gets made and reversed several times before the final release. The thrashing itself is part of the cost.

Waiting Causes Needless Infrastructure Adjustment Later

Delaying open sourcing also causes you to risk incurring extra overhead later from switching collaboration tools in mid-stream. A project run behind closed doors inevitably starts to use some of the internal collaboration infrastructure of the organization — infrastructure that won't be available to other contributors later when the project open sources.

Being open source from day one encourages you to take advantage of the robust ecosystem for open-source projects from day one instead: free project hosting, continuous-integration services that don't require paid membership if the project is open source, etc. Switching to these tools later, after your project is already under way, is a lot more work than just using them from the beginning.

Waiting Just Creates an Exposure Event

Another problem with opening up a completed code base is that it creates a needlessly significant exposure event. Whatever issues there may be in the code (modularity corner-cutting, security vulnerabilities, etc), they are all exposed to public scrutiny at once — the open-sourcing event becomes an opportunity for the technical blogosphere to pounce on the code and see what they can find.

Contrast that with the scenario where development was done in the open from the beginning: code changes come in one at a time, so problems are handled as they come up (and are often caught sooner, since there are more eyeballs on the code). Because changes reach the public at a low, continuous rate of exposure, no one blames your development team for the occasional corner-cutting or flawed code checkin. Everyone's been there, after all; these tradeoffs are inevitable in real-world development. As long as the technical debt is properly recorded in FIXME comments and bug reports, and any security issues are addressed promptly, it's fine. Yet if those same issues were to appear suddenly all at once, unsympathetic observers might jump on the aggregate exposure in a way they never would have if the issues had come up piecemeal in the normal course of development.

The importance of avoiding a needless exposure event is especially true for government projects, even more than for private-sector code. Elected officials and those who work for them are understandably sensitive to negative publicity, and are therefore risk-averse. Even if your team has been very conscientious, a worrying cloud of uncertainty will surround everything by the time you're ready to open up hitherto closed code. How can you ever know you've got it all cleaned up? You do your best, but you can never be totally sure some hawk-eyed hacker out there won't spot something embarrassing after the release. The team worries, and worry is an energy drain: it causes them to spend time chasing down ghosts, yet at the same time can cause them to unconsciously avoid constructive steps that might risk exposing real problems.

(For private-sector code, there are sometimes competitive reasons to stay closed until the first release, even if the project is intended to be open source in the long run. This is not an exception to the advice given here, it is simply a countervailing factor that should be weighed along with every other strategic consideration related to the project. One temptation to be suspicious of, however, is the notion that creating an exposure event is actually desirable — that dramatically open sourcing the code can itself provide useful publicity. In almost all cases, the better way to achieve that publicity would be by announcing the software's “1.0” release later on. The feature set and product stability that that event represents is what users and partners actually care about, and that announcement gives potential contributors another natural moment to take interest, or renew their interest, in the open source code base.)

The Good News

The good news is that these are all unforced errors. A project incurs little or no extra cost by avoiding them in the simplest way possible: by running the project in the open from Day One.

“In the open” means the following things are publicly accessible, in standard formats, from the first day of the project: the code repository, bug tracker, design documents, user documentation, wiki (if any), and developer discussion forums. It also means the code and documentation are placed under an open source license, of course. It also means your team's day-to-day work takes place in the publicly visible area (except for sensitive configuration data and the like — that of course stays behind your firewall).

“In the open” does not have to mean: allowing strangers to check code into your repository (they're free to copy it into their own repository, if they want, and work with it there); allowing anyone to file bug reports in your tracker (you're free to choose your own QA process, and if allowing reports from strangers doesn't help you, you don't have to do it); reading and responding to every bug report filed, even if you do allow strangers to file; responding to every question people ask in the forums (even if you moderate them through); reviewing every patch or suggestion posted, when doing so may cost valuable development time; etc.

Think of it this way: you open source your code, not your developers' time. One of those resources is infinite, the other is not. You'll have to determine whether engaging with outside users and developers makes sense for your project or not. In the long run it usually does, when done with care — different types of projects want different types of engagement. But the important thing is, it's all under your control. Developing in the open does not change the degree of control you have over the project, it just ensures that everything you do is, by definition, done in a way that's compatible with being open source. And you get that for free.

Open Source Helps Executive and Stakeholders

For executives and other stakeholders, early open-sourcing brings advantages too. The same collaboration tools used by the developers to coordinate work also provide visibility into that work for others. This is described well by Vinod Sankaranarayanan at ThoughtWorks; although he is writing there from an Agile perspective, his points apply quite clearly to open source as well (which is not a coincidence — there has always been a lot of overlap between the two).

Working in the open from day one also improves stakeholder trust through transparency. Rebecca Refoy-Sidibe of 18F wrote about how they polled the agencies they work with — that is, their customers — to find out how the experience was for them. Here's just one sample, from the Department of Justice:

Department of Justice’s Office of Information Policy: The biggest benefit we saw from the open source approach was the active feedback, engagement, and buy-in from our public stakeholders. We had more confidence that what would be released to production would be of value because we had solicited and considered input from a diverse stakeholder group.

Open Sourcing Earlier Benefits Others Earlier

As Eric Mill of 18F writes in Working in public from day one:

Even if you're working on what you think is the most niche project that no one else would ever use: leave the door open for providence.

You can't know all the other organizations out there and what they need. They will always know their own needs best. Give them the opportunity to benefit from your work — and perhaps contribute to it — on their schedule.

The benefit they get is not only technical. When you make your code open source from the start, you provide an example that internal advocates for open source at other organizations can point to. "Look, they're doing their project as open source, so why can't we?" Running your project in the open gives credibility to the notion of open source development as a normal practice, and the sooner you open source, the sooner you make that example available to others who may urgently need it.

Earlier I wrote that community management is under your control: it's something you do by choice, because of the benefits it brings to your project. But community management is also easier to control when scaled smoothly. It's much better for your team to start doing it early, instead of suddenly dealing with an influx of interest at the same time as version 1.0 is launched. At the beginning stages of a project, the early adopters who show up tend to bring a lot of value, and receiving that value is relatively low-effort because it's all coming form a small number of people. But the skills learned from handling those early contributors will pay off down the road. Start building the community management muscle memory early, when it's cheap, so that later when the community is larger your team already knows how to do it efficiently.

Conclusion

If you want your software to be on-time, on-budget, feature-complete, and open source, then just develop it the way you normally would but with everything open source from the start. You'll still only get two of the first three, of course — there's no escaping the Project Management Triangle. But you'll be taking the most efficient and effective route to being open source, and the project will be better off for it.

Field Guide To Open Source Project Archetypes

2018-05-15T15:53:00-04:00

Open source is a broad term that encompasses many different types of projects. There is a wide range of open source approaches, and sometimes it helps to think through how your open source approach matches your goals, resources, and environment. In many places we look, we see open source used as a catch-all term to refer to every project. We don't have a common vocabulary to discuss open source in ways that take account of important differences.

OTS prepared a field guide to open source project archetypes with Mozilla that is a first step in addressing that problem. The report catalogs a number of open source archetypes we observe around the community. OTS and Mozilla have found these archetypes to be a useful resource when crafting strategy, weighing tradeoffs, and committing support to open source endeavors. Today, we share the results of this work with the community.

[embed]https://youtu.be/Lo61OOi8_4Y[/embed]

We hope it is useful to you as you design open source initiatives, weigh tradeoffs in strategy, and pick metrics to track success. The archetypes we list are useful comparison points for anybody trying to maximize the benefits of their open source investment.

You can download the report here. Mozilla blogged about it. We also put the source text on GitHub and are inviting contributions to future versions. Finally, please drop us a line at archetypes AT opentechstrategies.com if you have comments.

Decentralization: Worth The Wait

2017-09-12T00:42:00-04:00

Ethan Zuckerman has a piece in Wired that says building decentralization tools is a sucker's bet. He and his coauthors, Chelsea Barabas and Neha Narula, mention the FreedomBox, which I helped lead, as an example of how difficult this stuff is. They point to a list of things that make decentralized efforts prone to failure and conclude:

Our research—a combination of technical and historical analysis, and dozens of interviews with open web advocates—indicates that there is no straightforward technical solution to the problem of platform monopolies. Moreover, it’s not clear we can solve the nuanced issues of centralization by pushing for "re-decentralization" of publishing online. The reality is that most people do not want to run their own web servers or social network nodes. They want to engage with the web through friendlier platforms, and these platforms will be constrained by the same forces that drive consolidation today.

They point to a "better strategy" of policies aimed at "data portability, interoperability, and alternatives to advertising-based funding models".

I'm no longer with FreedomBox, and none of what they write is wrong (I was one of the open web advocates they interviewed), but I wanted to chime in because there's more to decentralization than seeking a "straightforward technical solution" and building a better social networking app. It's true that we haven't realized the grand vision of Diaspora and FreedomBox. They're right that we need enlightened policy. We need the centralized platform monopolies to behave better. Those steps, though, won't ever give people control over the means of communication. Without that control, we'll always be at the mercy of Facebook or whatever comes next.

Redecentralizing the web is hard. FreedomBox and other projects I've worked with found that delivering exciting, secure, privacy-respecting apps required starting from scratch. Every piece of centralized tech depends on a bunch of other pieces that also tend toward the efficiency of centralization. Most of it is invisible to end users but it's centralized pieces all the way down. We wanted to build a beautiful fountain but were missing basic plumbing. If you want to fundamentally change the relationships between the visible parts, you can't just skim the surface. You have to dive deep and you need to invent all the decentralized building blocks that make up a complete web service.

It's a little like switching cars from gas to electricity. You can't just aim sunbeams at your fuel tank. You have to change every moving part in the vehicle, rethink gas stations, reinvent batteries, redesign a chunk of the electric grid, adopt new regulations, grow a new supply chain, and maybe fundamentally change the average person's relationship to their car.

The internal combustion car and all the pieces of our world that relate to it benefited from billions of dollars of investment and a century of development. We're not going to shift everybody to electric cars overnight. With all the might of the car companies, it will still take decades of small changes, each one ambitious on its own. Likewise, we're not going to dislodge the Internet monopolies overnight with weekend coders and money begged on Kickstarter.

What we're going to do instead is start at the bottom and build some boring infrastructure that makes other decentralized things possible. That piece will make new decentralized work possible. Those efforts will also be boring to everybody except privacy geeks. But we'll keep building and refining. Eventually we'll have a towering stack of pieces, each providing some crucial bit of decentralized functionality. They'll add up to something that, finally, some end users want.

And when that thing is built, nobody will notice. Unless you care what's under the hood, it will be boring, like a Prius. People who use it will like that it works well and respects their privacy, but they will understand decentralization about as well as they get battery chemistry or regenerative braking.

That is what we're building towards. All of Zuckerman's points about this being a monumental task are true. We should pursue the policies he identifies. But we should firmly reject any suggestion that we stop building just because it's hard and will take a while.

Report on GeoNode's path to open source success

2017-06-15T19:31:00-04:00

Recently, OTS was asked to write a report about the GeoNode project by one of its primary sponsors, the Global Facility for Disaster Reduction and Recovery (GFDRR) a global partnership that is managed by the World Bank. GeoNode is a facility for sharing and displaying geographical information. It is "web-based, open source software that enables organizations to easily create catalogs of geospatial data, and that allows users to access, share, and visualize that data," as we put it in our report.

GFDRR and its Open Data for Resilience Initiative (OpenDRI) work to increase community resilience to natural disasters, in particular by sharing data. GeoNode helps them do this by providing a way to easily share geographical data - what parts of a city are the lowest and most prone to flooding? Where exactly has an earthquake hit, and where is assistance needed most quickly?

Why write a report?

OpenDRI began the GeoNode project in 2009, and has been a major contributor to the code and community since then. In 2016, they decided that they'd like to contribute in another way: GeoNode as a project has been tremendously successful, and they wanted to share lessons about how to incubate an open source project. Large institutions sometimes sponsor open source projects, and do not always have success involving partners to the extent they would like. OpenDRI brought in major partners and is now no longer the primary contributor to GeoNode's development. They would like to be able to replicate this success in future projects, and wanted to offer an example to the open source community about releasing and cultivating a project like this. To clarify the example, OpenDRI asked OTS to write a report about the GeoNode project.

Our process

To complete the report, we interviewed participants in the project, from
people who had been involved from the very beginning to more recent
additions.  In general, we strove to get perspectives from people from
different levels of the contributing organizations -- not just
developers, but decision-makers and funders.  We also looked back at
tangible evidence from the earlier days of the project: commits, mailing
list archives, blog posts, and documents generated from early in-person
meetings.

Results

These interviews and research resulted in 9 major lessons for organizations starting future open source projects:

Run as an open source project from the very beginning
Engage other organizations commercially
Focus on communications and evangelism early
Find and encourage the right partners
Invest in collaboration infrastructure
Hold events and sponsor attendance
Use funding choices as a signal to peer institutions
Improve user experience to attract new users
Change the nature of your investment as needed

Flexibility and openness were both key for OpenDRI's success. While GeoNode benefited from having been built on existing open source libraries and platforms, its widespread use and adoption were due just as much if not more to the openness of its community. Its early supporters at OpenDRI shared it widely with similar organizations and worked hard to invite in new contributors.

The full report is available from OpenDRI - see their summary and a download link here, and their announcement blog post for more.

"Open source mistakes for enterprise newcomers" on O'Reilly Radar

2017-05-10T20:40:00-04:00

OTS partners James Vasile and Karl Fogel recently wrote a post for O'Reilly Radar about common mistakes that companies make when they start to get involved in open source. They write:

Open source reinvents relationships and business dynamics, turning customers and even competitors into collaborators. Firms embrace it to encourage those dynamics, when the benefits of participating outweigh the gains from going it alone with proprietary code. But open source isn't an outcome in itself. It is an approach for finding where different firms’ interests intersect and helping them cooperate there — but it is the path, not the place. To enjoy its full benefits, one must visibly walk that path.

Thanks to Andy Oram and Adam Flaherty for their expert editing and advice. You can read the full article on O'Reilly.

Attending the Wontfix Cabal

2017-02-24T15:21:00-05:00

GitHub hosted the "Wontfix Cabal" last week in San Francisco, and I was lucky enough to attend, thanks to a pointer from a friend. The organizers, led by Jess Frazelle, conceived the gathering as a chance for people maintaining open source projects to discuss their particular difficulties and some strategies for addressing them. About 100 maintainers took them up on it and convened in San Francisco. At the beginning of the day, we compiled dozens of sticky notes worth of problems that come up in our various projects. These ranged from tips for maintainers who had received the classic question "Is this project still maintained?" to "Ethics and Exploitation in Open Source." In a common unconference pattern, attendees voted on those topics. The most popular topics were chosen to become discussion groups, and we split up for a morning session and an afternoon session.

In the morning, I joined the "Code Review" discussion group. At OTS, we frequently advise clients who aren't familiar with the ins and outs of accepting and reviewing contributions from outside parties. This group confirmed our best practices around code review, and reaffirmed its importance. Much of this particular discussion was about projects with an overabundance of pull requests (PRs), which is of course a good problem to have.

A few themes emerged:

Encourage contributors to start a conversation before putting in too much time and effort. The discussion phrased this as "open an issue before submitting a PR," but really the goal is to avoid a situation where a contributor puts a lot of work and time into a pull request that the maintainers don't want to accept. If the person opens an issue for their proposed change, that gives project maintainers an opportunity to respond with reasons why they wouldn't accept a PR with that change. For small changes, opening a PR might be enough to start the conversation, and making a separate issue could be too much overhead. The important thing to communicate to contributors is that they should be checking in with the project's maintainers on the direction of their work when they begin.
Use GitHub's templates for PRs and issues. These save time by giving contributors a clear idea of what kind of information the project expects, like a DCO (Developer Certificate of Origin), tests for any new functionality, and updates to the documentation. Templates also allow projects to use bots for initial review and response to new contributions.
Automate initial responses. Responding to PRs and issues with bots saves time for the maintainers while still ensuring that contributors get a response (to retain contributors, it's crucial to engage with them -- that attention is their reward for contributing). Another discussion group pointed out that contributors might take more kindly to being corrected by a bot than by a person. Robots aren't judging, so the embarrassment of getting something wrong is much reduced when it's a bot pointing out the mistake.

In the afternoon, I joined a group on "internal versus external contributions." That is, what happens if an open source project is primarily sponsored by just one company? For one thing, sometimes that company's priorities will not line up with those of the community. See the full notes here. Some of the main points were relatively straightforward: make clear to contributors what kind of governance your project has, or if it has none. Determine early whether this is primarily a community-driven or a company-driven project, and indicate that to everyone involved. Overall, make sure that the decision-making process is clear.

One part of this discussion that surprised me was how few of the long-lived, well-known projects represented in the group had any kind of formal governance procedure. Kubernetes was mentioned as an example of a project that does have explicit governance. Many others, though, do not. One recommendation that came out of this session was to research and adopt governance practices in more of these single-company-led projects. This calls back to the determination to "be clear about the decision-making process." It's fine if internal contributors have outsize influence on project direction, so long as that is communicated at the outset.

I was glad to see that this is consistent with the advice OTS typically gives our clients: don't worry about governance too soon! Our clients are frequently concerned about how to set up their governance structures before they have a single outside contributor. The fact that many successful and widely used projects don't have formal governance until their lack of it becomes a problem is just more evidence in favor of deferring these structures, which can quash early project momentum. There is little need to worry about governance until conflicting priorities between contributor groups become apparent. Later in a project's life, however, more explicit governance is crucial in order to avoid forks.

Most of the conference went on outside these specific sessions. We spent twelve hours together, talking about current projects, aspirations for our communities, opportunities for mentoring, and more. I'm thrilled that I was able to attend -- meeting the other attendees was fascinating, as was hearing about different approaches to maintainership. Many thanks to the organizers and sponsors for making this possible. I don't yet know if there'll be a follow-up next year, but if so, count me in.

Sharing data across Red Cross projects: the Smoke Alarm Portal and allReady

2016-11-29T21:15:00-05:00

OTS has been lucky enough to work with the Red Cross of Chicago and Northern Illinois (CNI) for the past year and a half, thanks in large part to the civic data community at Chi Hack Night. With Jim McGowan, CNI's Director of Planning and Situational Awareness, we developed the open source Smoke Alarm Request Portal, where you can request to have a volunteer come install a smoke alarm in your home for free.

Now we're connecting the Smoke Alarm Request Portal to allReady, an open source platform for volunteer preparedness and coordination (part of the Humanitarian Toolbox suite of disaster preparedness and prevention tools). With help from both open source communities, the two applications will share data to simplify the process of scheduling smoke alarm installations.

The Red Cross and open source

The American Red Cross is a volunteer-driven organization: their disaster relief and prevention campaigns depend on the work of many people who are not on staff. CNI in particular believes that this focus on recruiting, training, and involving volunteers across their organization means that they should run their software initiatives as collaborative open source projects. Open source offers their volunteers another way to be involved in their work, and allows people who may not be able to offer time on the ground a way to contribute to the Red Cross' mission.

Smoke Alarm Portal

The Red Cross currently has a goal to reduce home fire deaths and injuries in the United States by 25% by 2020 (see their resources page on home fires). One piece of their campaign to prevent fires is free smoke alarm installation. Anyone can sign up to receive a free smoke alarm for their home, and Red Cross staff and volunteers will bring and install one or more as needed.

CNI was already accepting smoke alarm installation requests by phone, but they (and the rest of the Northern Division) realized they could manage requests much more efficiently via the web. They just needed a simple application where users could request a free smoke alarm. OTS built an open source application and deployed it at getasmokealarm.org. See the project on GitHub to see the code, or to get involved (as many people have).

Humanitarian Toolbox and allReady

While the Smoke Alarm Portal was being developed, Jim McGowan began working with the Humanitarian Toolbox (HTBox) project on an ambitious open source solution to increase community resilience and disaster prevention efficiency. The allReady project, as described in their announcement blog post and project page, aspires to "put disaster out of business" by increasing the resiliency of communities across America. Its goal is to be a central application for coordinating volunteers across disaster prevention and relief campaigns for the use of non-profit groups like the Red Cross as well as town and city governments. (See the allReady GitHub page here.)

Bringing them together

Since allReady aims to be the central warehouse of all disaster prevention data for its users, it's only natural that it should be used as an interface into the Smoke Alarm Portal. Even before allReady is in production, OTS is working with the HTBox team to add API endpoints to both projects that will allow Red Cross volunteers to update the status of smoke alarm requests from within allReady, without affecting the workflow for people requesting smoke alarm installation.

Once this work is complete, end users will only need to interact with getasmokealarm.org, while administrative users (Red Cross volunteers and staff, in this case) can sign in to manage smoke alarm requests and other kinds of prevention work from within allReady. If a Red Cross staffer knows that a volunteer team is going to a neighborhood to install smoke alarms, they might also be able to stop and drop off supplies for a family in the same area that recently suffered a different kind of emergency. Once the volunteers update the smoke alarm installation status in allReady, that application will also update the status in the Smoke Alarm Portal.

Next steps

Linking allReady with the Smoke Alarm Portal is still in progress. We're happy to work with anyone who wants to to improve and test the endpoints on both projects, to review documentation, and to give feedback on design. Most importantly, though, let your local disaster prevention groups know about allReady and the Smoke Alarm Portal, and check the batteries in your smoke alarms!

Open Source Code of Conduct for Commercial Entities (DRAFT)

2016-06-03T10:05:00-04:00

Note: This is a draft of a Code of Conduct meant to help a specific open source project give guidance to its commercial participants. The project is already in production use, and is successful enough that some commercial entities have become involved, offering support, hosting services, customization, etc. However, those companies need some guidelines about how to conduct themselves, in relation to the project as a whole and in relation to each other.

The first half of the draft is aimed at commercial entities. The second half of the draft contains guidelines for the open source project itself — healthy commercial participation being a two-way street.

Once the text is finalized, we plan is to post this in generic form, as a template that other projects can use, while delivering a customized version to that project.

In the meantime, comments welcome! You can simply leave regular blog comments, but we've also enabled the open source Hypothes.is WordPress annotation plugin to allow sidebar annotations of selected text. To use it, just mouse-select any passage of text, as though you were going to copy it to the clipboard, and then wait for the Hypothes.is annotation action buttons to pop up right under your selected text. There should be two of them: "Annotate" and "Highlight". Choose "Annotate", and then, at the top of the right-hand sidebar that should now open up, create a free account at Hypothes.is, or sign in if you already have an account. (We need the authentication step to help prevent spam annotations.) Once you are signed in, you can leave a sidebar comment associated with a specific passage of text — the user interface should be pretty clear from this point on. Please note that your comments will be publicly visible by default; you can also make an annnotation that's private to yourself, but then we wouldn't be able to see it either of course.

Open Source Code of Conduct for Commercial Entities (DRAFT)

The [Your Project Here] Project welcomes involvement from commercial entities. The availability of multiple sources of commercial support is important to the project's long-term health, and to making [Your Project Here] a persuasive choice for organizations around the world. Commercial support can include but is not limited to hosting, on-site deployment and installation, advocacy, PR and event funding, administrative services, customization, and even implementation of new features.

This code of conduct provides guidance for commercial entities wishing to participate in the [Your Project Here] ecosystem. While the specific items in the code may be revised from time to time, overall the code is based on a simple principle:

Commercial entities should observe the distinction between public community functions and private commercial functions, and ensure that their activities support (or at least do not harm) the public community.

The first half of these guidelines is meant for commercial entities, but the second half is meant for the open source project as a whole, since a commercially healthy open source environment depends on everyone doing their part. Some of the guidelines are proscriptive, being based on situations that have arisen in the real world — in [Your Project Here] and elsewhere — but we also include some positive recommendations that can help commercial entities participate successfully.

Guidelines for Commercial Entities

- Treat the project's name with respect, and follow the project's trademark and branding policy.
  
  Don't use the project's name for things which are not related to nor supported by the project. In general, don't introduce confusion about what the project's name means and refers to. Also, don't seize the project's name in other public namespaces, e.g., in domain names, Twitter, GitHub, Slack, etc. (It is fine, however, to register the project's name in a new namespace and then immediately donate control of that account to the project — that's simply helping the project maintain its identity.)
- TBD: [Your Project Here] needs a trademark policy, for this item to be effective. See the item Have and enforce a formal trademark and branding policy in the section Guidelines for the Open Source Project for more about this.
- Don't replace community infrastructure; instead, improve it.
  
  For example, use the project's discussion forums as specified in their charters, instead of setting up duplicate forums in a privately-controlled space that could potentially siphon off people from the project's existing forums. I.e., don't set up "walled gardens" that detract from public spaces. The same principle applies to other kinds of community infrastructure too, e.g. wikis, but we'll use discussion forums as an example here.
  
  It is fine to set up private forums that are specific to commercial offerings, especially where those offerings differ from what is available in the open source project (though see below about avoiding the "enterprise edition" trap). Discussion that is specific to a company's commercial offering is only useful to that company's customers. But do not try to discourage customers from making use of the project's public forums when doing so would serve their needs.
  
  A good way for a company to ensure compliance with this guideline is to link to the relevant project forums from the same places — and in comparable ways — that the company links to its product-specific forums. That way customers will be aware of all the options available to them and can choose the appropriate forum for their needs. It also means that customers' questions, and the company's or others' responses to them, can contribute to the public store of knowledge about the project, which is an important way that commercial activity can support the long-term health of the project. Company representatives should include their affiliation in the support responses they make to customers or to anyone else; work the company performs publicly is still work that it did, and the company should get credit for its contributions.
- Label the company's offerings in a way that makes their provenance clear, and that does not denigrate or diminish the open source project.
  
  Specifically, do not label a proprietary offering as the "Commercial Edition" or "Enterprise Edition" of the project, especially not in contrast to a so-called "Community Edition" as a euphemism for the project's open source code. That kind of marketing implies that the open source edition is somehow not commercial (which would be untrue, as the open source license explicitly allows commercial activity by anyone) or not enterprise-ready (unlikely to be true, but in any case ill-defined).
  
  Instead, give the company's offerings their own distinctive names. If those names incorporate the name of the project in some way, that may be fine so long as it complies with the project's trademark guidelines. It is also fine to offer fact-based comparisons between the company's proprietary offering and the stock open source version, or between this company's offering and others' proprietary offerings. Or if the offering is also open source software, but differs from the project's offering in some significant way, explain that, and again make sure the company's offering has a name that clearly distinguishes it from the code released by the project.
  
  The purpose of this guideline is to help the company communicate clearly about what it offers, and to help potential customers understand what differentiates this company's offerings from what is available elsewhere. There is nothing wrong with offering features not present in the project's open source releases, or with making different configuration choices from the project's defaults. Just describe the differences accurately and objectively. Mislabeling, whether accidental or deliberate, causes confusion and is bad for the project's health.
- Do not attempt to convert unofficial influence into claims of official control.
  
  Even if the company is a major contributor to the open source project, do not conflate the project's identity with the company's. If a company with a well-established position in the project casts too large a shadow, that may discourage involvement from others.
  
  For example, the company might have a number of employees as core committers in the project, and thus exercise a significant de facto influence over the project roadmap, simply by doing a lot of the work and participating actively in project development discussions. This is generally not a problem, as long as the company does not claim some official preferential position in project governance that it does not in fact hold.
- In public forums, the company's employees should behave like any other project participants.
  
  While management hierarchy may be important internally to the company, it is irrelevant to the public open source project. For example, if the company assigns an employee specifically to work on the project, expect that employee's contributions to still go through the usual review procedures, and expect that employee to gain commit access by the same route as anyone else would. Similarly, it is good practice for the company's employees to hold design discussions or other technical discussions in the project's public development forums, even if the employees normally sit in the same room and could discuss those things in person. The more they participate visibly in the project, the stronger the ties between the company and the project will be.
- Contribute to public activity, and avoid converting public conversations to private ones.
  
  When commercial representatives are active in an open source project's public forums, there will be many opportunities to turn public conversations into sales opportunities. This can be a good thing — often a potential customer will benefit from being contacted about a commercial offering, and commercial entities should feel free to establish such contact so long as they avoid harassing or spamming people. In general, if some user indicates needs that would be met by the company's product, it is reasonable to contact them about that directly, as long as the company is respectful of the charter of the forum in which it encountered the user and of any preferences they give about unsolicited commercial communications.
  
  However, it is important to avoid shunting conversations out of public forums, where inquiries and responses will remain visible to others, and into private forums, where the initiator would be isolated from other sources of information. The best way to avoid this anti-pattern is to distinguish carefully between answering questions and offering commercial services. The former should always be done via a public followup in the original forum where the question was asked, while the latter should happen via a separate private communication. A topic that started in public should remain public, and should not be interfered with or subsumed by private conversations.
- Improve project documentation, don't fork it.
  
  Help make the project's public documentation better, rather than duplicating and extending that documentation elsewhere. Even if the duplicate documentation is publicly accessible even to non-customers, it will still detract by its mere existence from the project's own documentation, among other things by causing confusion in Internet search engine results.
  
  It is fine for the company to maintain separate documentation for functionality that is specific to its product or service. But as much as possible, avoid duplicating material already present in the project's documentation. Instead, refer to the project's documentation, and, as much as necessary, participate in improving it and making it easier to refer to, so that the maintenance burden is reduced for the company and everyone else.
- Any restrictions in non-compete agreements should only affect business activity, not project activity.
  
  If the company requires employees or contractors to sign non-compete agreements, those agreements must not prevent the individual in question from participating in the open source project in any way, whether during or after the term of their employment.
  
  This does not mean that all non-compete agreements are incompatible with this code of conduct. A company may restrict an employee's ability to solicit the company's customers, for example. The key is that any restrictions should be about things other than project participation itself. An individual should not be blocked from any form of technical or social participation in the project, including the implementation of particular features.
  
  The accumulation of experience and expertise in individual persons, who are ultimately free to direct their energy and attention as they decide, is one of the most important drivers of progress in open source projects. A company that limits this freedom can damage the open source project very seriously.
- Security vulnerability information should always be promptly disclosed to the project.
  
  If a commercial entity learns about a security vulnerability in the open source code, it should always promptly disclose that information to the project using the project's designated channel for reporting such vulnerabilities. (Of course it is acceptable to pre-patch the company's own offerings, as long as that patching does not significantly delay the reporting of the vulnerability.)
  
  Vulnerability information should never be used for unilateral commercial advantage. Vendors may legitimately compete on the speed and reliability with which they deploy security fixes, but withholding vulnerability information damages everyone in the long run by risking harm to the project's reputation and the security of all users.
- Company staff should be forthright about the company's commercial interests.
  
  There is no need to hide motivations in an open source project. It is very normal for developers to propose that a certain capability be added to the code and justify the proposal on the grounds that it would help their employer's commercial interests. The best situation for the project is one in which developers communicate their priorities clearly and straightforwardly. As long as the proposed change goes through the project's usual decision-making procedures, the fact that it would serve specific commercial interests is not only not bad for the project, it may often be good: after all, continued commercial interest in the code is usually a good thing.
  
  Of course, it would be odd to make a technical proposal that is wildly divergent from the project's current roadmap and from the interests of all other parties participating in the project, but in that case the proposal is likely to be rejected anyway. In general, there is no need to pretend to purity of motivations. Finding sustainable resolutions to the tensions between various parties' needs is a long and well-established tradition in open source projects; as long as the company participates in those discussions in good faith, and compromises where appropriate, the influence of the company's commercial motivations is likely to be an overall benefit to the project.
Consider having a designated contact person or ombud, to represent community concerns internally.

Depending on the size of the company and the degree of its involvement in the open source project, it may wish to officialize a role for representing community concerns internally. In practice, this role is often assumed informally anyway, usually by an engineer or community manager who works for the company but who is active in and invested in the project. What the company can do is make sure this person feels comfortable raising project concerns internally.

Establishing that level of comfort is a matter of company culture, and obviously these guidelines cannot require nor enforce a particular corporate culture. All they can do is point out that the best way for executives to make informed decisions is by giving those closest to the project a chance to represent the project's interests honestly and accurately.

When this role is formalized, it is sometimes known as "Community Representative" or "Ombud" (or "Ombudsperson", "Ombudsman", etc). Whether this person's identity is known publicly or not, they should be reachable via a public contact address, with a prior commitment of confidentiality, so that others in the project have a way to raise concerns privately with the company when they wish to do so.

Guidelines for the Open Source Project

- Have and enforce a formal trademark and branding policy.
  
  Specify when and how the project's name and logo can be used without explicit permission, versus what uses require permission from the trademark holder. Ensure that the trademark holder is an institution that can be trusted to act in the project's long-term interests and that is not beholden to any particular commercial entities.
  
  Some examples of open source trademark policies are:
- Maintain discussion forums.
  
  Maintain discussion forums for developers and users of the project, make sure each forum has a written charter, and take whatever steps are necessary (e.g., moderation) to ensure that each forum remains useful for the purposes stated in its charter. All public forums should be publicly archived and have open membership.
  
  The project may also maintain non-public forums, such as a security vulnerability reporting and discussion group, but these non-public forums should still have public written charters that state their membership policy. Membership in non-public groups should be individual, but may take affiliation into account: for example, someone may be granted access to a security group in part because of their role at a commercial hosting provider that wishes to stay up-to-date with pre-release security patches. However, the potential member's discretion and trustworthiness should also be a factor, and they may retain their membership even if their affiliation with that commercial provider ends.
- Have a written explanation of how commit access is granted.
  
  There should be no mystery about how a developer becomes one of the official maintainers of the project. Maintain a written explanation of how new committers are chosen in the project. The process can be as simple as "current committers vote privately to invite a new committer"; the important thing is to document it so that contributors whose work is commercially sponsored understand that the system is fair and that the potential for them to be invited to become a committer is dependent primarily on the technical merits of their work and on the constructiveness of their interactions with the rest of the project community, rather than on their commercial affiliations.
  
  A few projects do place a limit on the fraction of core maintainers that may be affiliated with the same organization at the same time; in general, this kind of limit should only be imposed as a last resort, when the community has tangible concerns about dominance of project direction by one entity. Remember that open source projects are voluntary social constructs — a project can always be forked, even by its founders. Also, if a trusted entity controls the project's trademarks, then that is a powerful incentive to commercial interests to behave well.
  
  A good example of a simple but documented procedure for gaining commit access is this one from the LibreOffice project: https://wiki.documentfoundation.org/Development/GetUnrestrictedCommitAccess
- Maintain documentation, and make it easy for everyone to contribute to it.
  
  One of the most common commercial anti-patterns in open source projects is the phenomenon of a company maintaining a separate set of project documentation for its customers, often of higher quality than the project's official documentation. The company should instead contribute to improving the project's public documentation — but this implies a reciprocal obligation on the part of the project as a whole to being receptive to such documentation improvements. The project should view commercial support providers as a valuable source of information about deficiencies in project documentation: a company whose sales depend on customers having a smooth experience will be highly sensitive to the quality of documentation, and the project should try to leverage this sensitivity for everyone's benefit.
- Support and enforce this code of conduct publicly.
  
  The project should publicly recognize companies that abide by this code of conduct, and (after making a good-faith attempt to remedy any misunderstandings or problems) publicly chastise companies that violate the code.
  
  One method of publicly supporting companies who formally agree to abide by the code is to publish a list of such companies on the project's web site. The same entity that enforces trademarks for the project is usually the right entity to maintain that list. Being listed on the project's official site, as a commercial support provider who is certified as abiding by the project's commercial guidelines, is a valuable advertisement; the potential for removal from that list then becomes a powerful incentive for companies to live up to their pledges.
  
  If a commercial entity is violating the code of conduct, representatives from the project may choose to contact that entity privately at first, to see if the problem can be resolved quickly — often such problems result from misunderstandings, particularly with companies who are unaccustomed to working in an open source environment. However, if the problem cannot be resolved to the representative's satisfaction, then it is important to publicly state the code of conduct violation, documenting it thoroughly but without rancor, and emphasizing that the project welcomes participation from that entity so long as the entity complies with the code of conduct. This statement should be posted to the appropriate project discussion forum, so that the statement and any followup posts (either from the commercial entity or from other participants in the project) are visible and indexable by Internet search engines. The representative may, of course, choose to remove the commercial entity from the list of entities that abide by the code of conduct; such removals should be announced too.
Maintain a private contact address for reporting code-of-conduct violations.

The project should maintain a private contact mechanism by which anyone may report violations of this code of conduct. It is up to the project to decide who receives and acts on such reports. There is obviously potential for conflicts of interest if representatives of commercial entities are among the recipients, but compliant commercial entities are also those most motivated to be responsive to such reports, since it is strongly in their interests to detect and stop an incipient arms race of bad behavior. One way to alleviate such conflicts is to either allow no representatives of commercial entities, or to have representatives from mulitple entities, so that there are enough participants to prevent any one participant's interests from being overrepresented.

OS IV&V: Independent Verification and Validation for Open Source

2016-04-11T23:23:00-04:00

When you hire a development shop to build an open source product, you want to make sure the result is truly open source. You want to guarantee that:

The end product is independently deployable by others.
There are clear instructions for how to get involved.
Commercial third parties are welcome (because that's usually where new development energy comes from).
There are no unexpected proprietary dependencies.
The developers respond constructively to bug reports.
There are procedures in place (as there should be for any software) for receiving sensitive security vulnerability reports.
The project is poised to become a multi-participant and even multi-vendor community.

However, often first forays into open source do not meet these goals — not because of bad intentions, but because vendors who are new to open source need some help.

Open Source IV&V provides vendors that help. An independent vendor specializing in open source works alongside the development vendor, playing the role of open source community from the start of the project. The IV&V vendor works with the development vendor out in the open, just as third-party participants would. By the time the first production release is ready, the development vendor knows how to navigate an open source project, technically and culturally.

OS IV&V helps expand the range of vendors you can consider hiring to do open source development, and it ensures that by the time the project reaches beta, there are at least two vendors who have technical and deployment knowledge of the code base.

The long version:

Traditionally, “Independent Verification and Validation” (IV&V)1 is a method of independent oversight for technical projects, in which a disinterested third party is brought in to test that a project’s results fully meet the specifications as set out by the client. It is most commonly used with private-sector contractors delivering technical work to a government agency. For example, NASA has been using IV&V arrangements for many years to ensure that its contractors — and its own engineers — are meeting safety and cost-effectiveness requirements.

“Open Source IV&V” is designed specifically for open source software projects, and its purpose is to not only ensure that the end product is legitimately open source software, but that the project is created and managed in a sustainably open source way, which sometimes can include changes in how the customer and contractor relate to each other.

We have gradually designed the OS IV&V process through the repeated experience of being brought into projects after development is already under way with a primary development vendor — often one that does not have extensive experience with open source practices — and then attempting to retroactively transform the work into a real open source project, with all the benefits open source can bring.

In open source software, the result of a project is not merely the software code itself. It’s also the ecosystem around the code: all the publicly-visible discussions between developers and users, all tickets in the bug tracker (each ticket recording not just a technical fact about the software, but also a conversational dynamic between different people at different organizations), all the feedback from both automated and manual testing, contributions from interested third parties (some of these contributions may be already incorporated, others may be still pending review), a project roadmap reflecting input from multiple sources, documentation not just about using the software but about how to contribute to the software, etc.

The health of this larger ecosystem is crucial to the long-term success of the project, and to reaping the benefits of open source. What OS IV&V verifies and validates is not just the technical components of a project — code, licensing, documentation, open source collaboration infrastructure, etc — but also the contractor/customer relationship: how communication happens, how they bring in third-parties as the project grows, how they handle user feedback, etc. The goal of OS IV&V is help the customer and the development contractor structure their working relationship in a way that is compatible with the project flourishing as an open source ecosystem.

Why is OS IV&V necessary?

When a software contractor who has little or no experience running open source projects agrees to create an open source product for a customer (say, for a government agency), the contractor usually fails to adopt standard open source processes from the beginning of the project. For example, the contractor often does not ensure that development happens in the open from the start, is not prepared to integrate commercial or volunteer third-party involvement, does not use typical open source tools and procedures to receive and handle user feedback publicly (nor have proper procedures in place for receiving security vulnerability reports), does not post clear instructions for how to join the development effort, does not encourage its developers to be responsive to genuine technical inquiries, etc.

This is because most primary development contractors are accustomed to doing software development entirely in-house, and simply continue to use in-house techniques even after taking on an open source contract. They use an internal bug-tracking system from which tickets cannot be made public, they use internal code repository servers because that’s what their developers are set up to use, they write documentation in proprietary formats aimed at a primarily in-house audience, and so on. Most importantly, they and their customers tend to communicate almost exclusively in private about the projects they work on together. A typical workflow is that the customer submits feedback by sending private email to some designated contact point at the contractor, which results in a private ticket being filed in the contractor’s bug-tracking system; the customer may know the bug ticket number but often not even have read-only — let alone read-write — access to ticket itself.

To get the full benefits of open source, the contractor needs to adopt practices that may be unfamiliar, and the customer and contractor need to use an open source approach to their own communications around the project. A project that is run in a truly open source manner will be much better able to engage third-party interest, which in turn makes innovation by other companies much more likely, and naturally lowers the customer’s risk of vendor lock-in. It also, in our experience, results in higher-quality, more easily maintainable software.

The role of the OS IV&V vendor is as much to assist both sides in making these adjustments, as it is to verify and validate that the adjustments have been made. A successful OS IV&V engagement results in a new way of working that is repeatable for future projects.

Elements of OS IV&V

Although OS IV&V is as much an art as a science, we have done enough of it now to extract some key ingredients. An OS IV&V vendor should ensure that:

The project is conducted in the open from day one:
- - Source code checked into a public repository (e.g., at GitHub)
    - - Corollary: The public repository has to be the master repository. Make sure there is not some internal private repository where the real development is happening, with tranches of commits occasionally exported in a throw-it-over-the-wall fashion to the public repository.
  - Public bug-tracker
    - - As with the repository, the public bug tracker must be the primary bug tracker.
  - Public documentation
    - - There is often a wealth of necessary documentation that the contractor considers to be private deployment documentation, but that is actually necessary for anyone trying to deploy the project, even just for development purposes. The OS IV&V vendor needs to sniff that out and help that stuff see the light of day.
Communications forums are available and configured according to open source norms (e.g., publicly archived, publicly subscribable via email or web, etc)
The appropriate people (from the contractor and the customer) are responsive in those forums
- - Corollary: Ensure that conversations don’t get silently sidetracked into private forums where they are inaccessible to the rest of the project; make an exception for when privacy is actually necessary, of course.
The project does not acquire any proprietary dependencies except those explicitly required (if any) by its specifications, and the code is compatibly licensed for outbound distribution under an open source license of the customer’s choice.
The customer is the copyright owner of the code, unless otherwise specified, and is named as such in the copyright notices in the source tree.
Development procedures are properly documented, and follow open source norms
- - A third-party developer should be able to deploy the software, for testing or for development sandboxing, using only the instructions and sample data provided by the public project.
  - There is a documented path for receiving and reviewing incoming third-party contributions, whether commercially solicited, volunteer, or due to some other motivation. This includes establishing DCO (developer certificate of origin) and/or CLA (contributor license agreement) procedures as needed.
  - Automated testing and continuous integration are set up in such a way that they are available to all developers, not just to the primary development contractor.
Deployment procedures are thoroughly documented and follow open source norms.
- - Sample data is available, in the formats developers would expect.
Secure coding practices and procedures for handling vulnerability reports are in place and are followed.
The primary development vendor and the customer use standard OSS communications channels for as much of their communications as possible.
The project is compatible with any relevant open standards, or at least acknowledges the relevance of those standards and has a long-term plan for compatibility.
The project has the governance policies it needs at every stage. This includes both ensuring that governance structures are not baked in too early, which would risk stifling potential early contributors with too much bureaucracy, and making sure that reasonable governance structure is added as more participants join the project.
Normal open source practices for receiving, recording, and handling user feedback are documented and followed.
- - This includes feedback from the primary customer: it should be submitted and processed using the same channels as any other feedback. The development contractor may prioritize it differently from other feedback, of course, but that does not change where and how the customer’s feedback is submitted.
Potentially adverse public events are anticipated (or swiftly detected) and handled.
- - Assistance with planned events, such as launch announcements, to ensure that they keep the audience of potential contributors in mind.
  - Assistance with unplanned events, such as the discovery of a “zero day” security vulnerability, a data leak, etc.
Hackathons and other events that invite the public to become more involved in the project are conducted effectively. The exact assistance an OS IV&V vendor provides here can vary widely, depending on the experience and inclination of the primary development vendor, and can extend as far as the OS IV&V vendor being the chief organizer for such events, though of course the primary development vendor should still be included in whatever way they can be.
There is effective, high-quality mentoring provided if the project participates in the Google Summer of Code program2, the Outreachy program3, and other similar formal third-party contribution programs. Again, if the primary development vendor is inclined to take an active role in these programs, then the OS IV&V vendor can step back and merely provide assistance where needed; but the OS IV&V vendor can also directly arrange and mentor participation in the program if the customer and the primary development vendor agree.
The project publishes estimates of deployment costs and monthly marginal costs, for hosting of typical datasets. These estimates help facilitate involvement by other commercial entities, and are difficult for the primary development vendor to provide, both because the development vendor often designed the software around skills or hosting configurations they already had in place (and are thus unsuited to estimate a newcomer’s adoption of), and because their potential conflict of interest is too strong in any case.
Deployed code matches public code. That is, when the primary development vendor is also the hosting provider, as is commonly the case, their hosting SLA must not serve as a de facto justification for a divergent internal fork. Any deployment-specific customizations must be propagated back to the public, “upstream” version in an appropriate fashion, except for traditionally non-distributed minor customizations such as configuration file parameters, passwords, etc.

Structuring an OS IV&V Relationship

The OS IV&V vendor reports to customer, not to any of the development contractors, and only the customer decides whether the OS IV&V vendor is fulfilling their responsibilities. This is crucial: if the OS IV&V vendor were instead responsible to a development contractor, it could not provide the independent verification and unbiased advice that is the core of OS IV&V’s value.

This does not affect contracting relationships. It is fine, for example, for an OS IV&V vendor to contract through the development vendor simply as a prime contracting vehicle, or for both to subcontract through some other vendor as the prime, as long as the reporting relationship is clear: OS IV&V reports to the customer and no one else.

The OS IV&V vendor is also best positioned to assist the customer in higher-level planning related to the project, such as drafting extensions to the development contract, writing future RFIs and RFPs, and budgeting for post-deployment maintenance and enhancement, because the OS IV&V vendor has far fewer conflict of interests in these matters than the primary development vendor.

The OS IV&V vendor can also assist with the presentation of the project to potential partners, including to the local development community (particularly useful in large municipalities), or to relevant open source or civic technology organizations. This also includes assistance with staffing and contractor evaluation, since the OS IV&V vendor’s work remains largely the same no matter what the balance is between customer-side in-house technical staff and the staff on the development contractor’s side. In general, OS IV&V may be thought of as an independent body whose role is evaluate other participants in the open source ecosystem.

OS IV&V As Backup Support Vendor

It is okay for an OS IV&V vendor to have the potential to become an independent provider of commercial support in the project themselves4. The best OS IV&V vendor is not just a management-consulting shop with the enough in-house development knowledge to provide technically competent oversight, but rather a software development shop in its own right, with direct experience performing the kinds of contracts that it now being asked to provide oversight for. This has several advantages. First, it’s easier to communicate credibly with the primary development vendor when one understands their line of work intimately. Second, it’s easier to anticipate the needs of potential third-party contributors when one has been in that position oneself. Third, from the customer’s point of view, part of the purpose of OS IV&V is that by the time of product launch, there will be two independent vendors who could deploy and support the software on a commercial basis. If the original development vendor is performing satisfactorily, then their contract can simply be extended. But if they are not, then there is an alternative readily at hand.

Footnotes

1 See https://en.wikipedia.org/wiki/Verification_and_validation for more discussion of IV&V in general and its history.

2 https://summerofcode.withgoogle.com/

3 https://www.gnome.org/outreachy/

4 Though it is of course advisable to drop their OS IV&V role with a customer once they start providing direct project-related services to that customer.

Dissecting The Myth That Open Source Software Is Not Commercial

2016-04-11T16:07:00-04:00

My piece "Dissecting The Myth That Open Source Software Is Not Commercial" has just been posted at the IEEE Software Blog. Comments over there, please.

Many thanks to editor Stefano Zacchiroli for editing, and for suggesting a post in the first place.

What OTS Does

2016-03-30T21:35:00-04:00

When I tell people that I work at an open source consulting company, I often get puzzled glances (or those agreeable nods that mean "I have no idea what you're talking about"). What does "open source consulting company" mean? What does OTS do, exactly?

Who are we?

At Open Tech Strategies we do open source development and process consulting for corporations, government agencies, and non-profits who want to produce or use open source software more effectively.

Okay, but what does that mean?

Why open source?

Formally, "open source" just means software code released under a free license. But publishing code that way often turns out to have very powerful effects, so a more useful way to think of open source is as a way of aligning your organization's goals and its production processes. When you are trying to extend the life or the applicability domain of a software project, improve transparency and accountability in your organization, collaborate more effectively with partners or volunteers, increase user engagement with a service, promote user privacy, or grow a vendor ecosystem, open source provides a ready-made set of practices and promises that enable your natural allies to find & join you in the effort.

Open sourcing a project doesn't necessarily mean giving up control, except insofar as you decide that that doing so better serves your goals, but it makes it possible for a project to grow beyond the interest or budget of just one organization; we'll look at some examples of that in later blog posts. And building on open source software means that organizations don't need to pay to re-invent technological wheels like content management or databases and can focus on their own specific needs.

(See also Ben Balter's excellent post "Why open source" for a more in-depth look at why organizations choose open source.)

So that's open source. What exactly does OTS do, though?

Usually, I describe our work as falling into one of a few different situations: building, opening, and buying.

Example Client #1: Builder

This first example client, Builder, needs a piece of software to complete their mission work. They might be a non-profit fighting homelessness or youth violence or a corporation that needs a new research tool. Builder decides to use an open source custom-built solution for reasons of cost-effectiveness, transparency, or one of the other points I mentioned above. Over the course of an agile development process, we meet with the end users of the product and involve them in testing as soon as there's anything to test at all. All of our development takes place in the open, and we maintain install documentation so that anyone could set up a sandbox instance of the project to try out. When this process is done, Builder has a working piece of software in production that can be set up and maintained by any software development team using our open code and documentation. Their partners can set up the same system, extend it, and share any enhancements they make with Builder. We often continue to work with the customer beyond this point, of course, but the software's "developer surface area" is now much greater than it would have been were it proprietary: both we and Builder have the ability to welcome new partners into the project, and being able to exercise that ability has proven quite useful.

Example Client #2: Opener

Another kind of client, Opener, comes to us with an existing software product. Possible Openers are a data visualization and outreach engine for astronomers or a transparency tool for governments. While the software product is not the entirety of Opener's mission, it is a crucial part of the work and face of the organization. For Opener, we focus on code resiliency, partner collaboration, contributor engagement, and (where applicable) development of a commercial ecosystem around the project. When we complete our work with Opener, they have a usably open source project that has clearly-documented code, findable discussion forums on the web, an issue tracker in use, and all the other affordances of a well-arranged open source project. The project is well-positioned to invite new collaborators and engage users.

Example Client #3: Buyer

A third type of client can be called Buyer. This client is an organization that wants to use and/or contribute to open source software, but needs advice on adapting their procurement processes and on how to invest strategically in software technology. Buyer might be a government agency that needs to set up definitions and standards around procuring and using open source software, or could be a foundation or corporation that wants to invest in open source but needs some advice on how to select and support the right projects. For Buyer, OTS researches the state of the field in their area of interest and provides recommendations for investment and/or procurement routes. When we complete our work with Buyer, we often deliver a highly specific report on the best ways they can use or invest in OSS. They are prepared to interact with open source in the way that best advances their strategic goals.

That's the story (mostly).

Naturally, not everything we do falls neatly into these categories of building, opening, and buying open source software. For example, we also offer advice for companies that want their employees to be able to contribute to upstream open source projects and helps open source projects draft CLAs or think through their business strategies. If you're a Builder, Opener, or Buyer or just have questions, feel free to reach out. Thanks for reading!