Guides

A Guide to Outbound Open Source Software

People can also download version 1.0 Guide as PDF here

The TODO Community is grateful to receive corrections and suggestions for improvements via this repo, which contains TODO guide’s updated documentation with the most recent version

Introduction

Goal and target audience

This guide is about how to contribute to or to launch an open source project (also called “outbound open source”) as a company. It aims to describe a complete and lean process, that can be implemented in companies of any size (large but also small or medium sized organizations). Companies can tailor the proposed procedure to their needs. I.e., depending on the size and situation of the company not all steps need to be implemented.

Maturity levels

Corporate adoption of open source software (OSS) can typically be classified with a model of maturity levels. These levels describe how OSS is used in an increasingly effective fashion to drive value and address business needs. One of the distinguishing factors for the different maturity levels is how outbound open source is handled in an organization. The insight that influencing the open source ecosystem is mainly done by participation in and contributing to open source projects is seen as a critical factor.

A typical maturity model of corporate open source adoption looks like this (see for example Haddad: Open Source Program Offices):

  1. Denial - No or unconscious use of open source
  2. Consumption - Passive use of open source software
  3. Participation - Engagement with open source communities
  4. Contribution - Pragmatic contributions to open source projects
  5. Leadership - Strategic involvement with open source to drive business value

To advance from one level to another, certain initiatives and structural and organizational elements are required.

Going from consumption to participation, for example, will start with informal engagement and low-effort activities such as reporting bugs in upstream projects, which typically is driven by technical needs. On that level, decisions about open source contributions will normally be ad-hoc and be taken for individual cases only.

Establishing dedicated decision making processes and formalizing contribution policies will lead to the next level. A typical step on this level is to establish an Open Source Program Office to support open source engagement and maintain an open source strategy and processes.

On the leadership level, contribution processes are mature and scale. Corresponding tool chains are implemented. Own projects with the goal to create new open source communities are started if that’s required and appropriate. This will typically come with leveraging open source foundations to enable cross-company collaboration to strategically use open source to accelerate creating business value.

A company may decide to not progress to levels which are based on more contributions, and it’s of course possible to build mature processes to consume open source software without contributing. In most cases, there will be some pressure to contribute back, though. This can arise from practical technical needs (missing functionalities or required bug fixes are typical reasons for contributing to open source projects), from the expectation to take responsibility in the open source ecosystem, or from the desire to reap the full benefits of the open source model.

How companies manage open source: Open Source Program Offices

An increasing number of organizations realized the tasks of managing open source in an enterprise and complex relationships that are inherent to the open source ecosystem when they are advancing in their engagement in open source. For this reason, many of them started Open Source Program Offices (OSPOs), something called differently, for example Open Source Technology Centers, Open Source Community Development Team etc. OSPOs are a designated place where open source is supported, nurtured, shared, explained, and grown inside an organization. With such an office in place, businesses can establish and execute on their open source strategies in clear terms and responsibilities, giving their leaders, developers, marketers, and other staff the processes and tools they need to make open source a success within their operations.

The TODO Group offers a set of guides on how to get started with an OSPO. Companies that are new to this topic, might want to first take a look at How to create an open source program

Motivation for open source contribution

There is a broad spectrum of motivations for contributing to open source projects or starting new projects. Here, we can only list some examples.

Build software faster and better

Consuming open source software typically increases the development speed and decreases development costs since one builds upon existing code and a working and tested functionality. One risk however is that required features or bug fixes are not provided by the community as quickly as needed. To mitigate that risk, it might make sense to build up the required skills and create these bug fixes and/or features yourself. Contributing them back to the upstream projects has important benefits:

Exercise strategic influence

In addition to the benefits of open source software wrt. development velocity and quality mentioned above, contributing to open source projects can also be important from a strategic point of view. In the open source world, reputation and the ability to influence is typically build up by engaging in the community and by contributing. Thus, contributions to open source projects can help to …

Companies sometimes have the tendency to use money to exert influence. With open source projects this is not the most effective method. The currency of influence is contributions, because open source projects are usually much more driven by the work of individuals than the decisions of committees. So contributions work much more directly and effectively than being a member in an organization or paying for support or other services.

Open source communities (particularly those run by the big open source foundations) provide a neutral place for collaboration between companies and other organizations. Thus, an open source approach could offer new ways of collaboration with suppliers, customers, partner and even competitors, just to mention industry- or domain-specific projects such as Linux Foundation Energy or Eclipse Tractus-X. Establishing open source communities can also be a powerful means to create and maintain ecosystems and to establish de facto standards.

Attract, grow and retain talents

Software (and therefore also open source software) becomes more and more ubiquitous in many products and areas. Thus, for many companies it is crucial to have a skilled and motivated software development workforce. This is not only true for software or cloud companies, but also for companies from other segments, such as traditional hardware producers who integrate software into their products more and more, or any other company which is becoming more dependent on software due to accelerating digital transformation. An open source strategy including open source contributions and community engagements supports this:

Give back and keep open source sustainable

Open source software development is living from its communities. As mentioned above, the consumption of open source software helps to decrease costs and speed up development, but that’s only possible because there is the community behind these projects maintaining the software. To keep the open source development model sustainable, each consumer of open source software has therefore the responsibility to think about ways how to support these projects. These are some ways of engagement and support:

It is important to understand that though open source software has no license costs when consuming it, it is not available for free. To keep these projects attractive for its consumers, steady engagement and support is required. That’s why it is important to have a strategy for open source contributions in place.

How to contribute to OSS projects

Building better relationships with the open source ecosystem has its own set of challenges, but it becomes easier if you have a clear plan to follow. Here are some guidelines to a number of practices that organizations can adopt.

Define your open source goal and strategy

Your open source strategy connects the plans for managing, participating in, and creating open source software with the business objectives that the plans serve. This can open up many opportunities and catalyze innovation. The TODO Group offers a dedicated guide to Setting an Open Source Strategy

Establish open source guiding principles and processes

Guiding principles

The procedure described in the following is designed to ensure that the company interests and its employees are protected. We also need to make sure that contributions are in line with copyright law, export regulations, data protection regulations and open source development best practices. On the other hand, the procedural burden for all to be involved stakeholders shall be low and the approval procedure should not take too much time.

Responsibility: decision rests with unit

General structure and scope of the process

Lean procedure

Boundary conditions

Process for expressing company approval for contributions

Why is it needed?

Why is there a need for a certain procedure at all?

First of all, the copyright law requires it.

For example, the German copyright act states in Section 69b: Authors in employment or service relationships (1) Where a computer program is created by an employee in the execution of his duties or following the instructions of his employer, the employer exclusively shall be entitled to exercise all economic rights in the computer program, unless otherwise agreed.

Source: German Copyright Act

This means that all the software developed in this context is the property of the employer - i.e., the company the developer is working for. At least the German copyright act does not limit the proprietorship to code developed during working hours or within the company IT infrastructure, it only scopes the context.

Secondly, a procedure is required to protect the company’s business interests as well as to protect the employee. Finally public code is like the business card of a company as well as of the developer who has written the code.

Outbound CLA

Some OSS projects as well as some OSS Foundations require a Contributor License Agreement (CLA) before they accept contributions. We know at least two different types of CLAs:

Whether none, one or both are required for contributions is usually described in files like CONTRIBUTING.md in the project repositories. The CCLA and the ICLA authored by the Apache Foundation are the de facto standard of CLAs and many OSS projects have adopted either one or both.

The purpose of a CLA is to provide confidence to the OSS project that the contributor is entitled to submit the contribution. A Developer Certificate of Origin (DCO) is a an alternative approach and more lightweight compared to a CLA.

Some CLAs also require to transfer additional rights to the project such as the right to release the code under an additional, often proprietary license. This is an asymmetric setup which puts contributors at a disadvantage. Therefore most companies will not contribute to these kind of projects.

The price of improved confidence for the OSS project is more overhead in the organization the contributor is working for. Especially in case of large corporations with several affiliates the effort of evaluating, signing and maintaining a CCLA shall not be underestimated.

Why is a CCLA causing additional effort in large organizations? Let’s briefly look at the CCLA of the Apache Foundation as an example:

Some CCLAs require that the copyright of the contributions are assigned to the OSS project/Foundation. Copyright assignment is a topic which causes even more effort and might not be accepted at all.

Besides the above-mentioned additional effort the CCLA adds additional “maintenance effort” to the organization, because it requires that the organization nominates all entitled contributors by name to the CCLA requiring party.

It is your responsibility to notify the Foundation when any change is required to the list of designated employees authorized to submit Contributions on behalf of the Corporation, or to the Corporation’s Point of Contact with the Foundation.

This additional effort may hold organizations off to contribute small bug fixes or patches or even new features to the upstream OSS projects and puts them to risk of private forks and thus a lot of additional development effort in the long run. Thus the decision not to contribute needs to be taken very carefully.

A DCO in contrast to a CLA is a much more lightweight procedure. It was introduced to enhance the confidence that contributions to the Linux kernel are made “legally correct” by the contributors. The DCO version 1.1 is used by many OSS projects.

The main difference of a DCO compared to a CLA is, that a DCO is not a contract, it is a kind of attestation of the specific contributor that they are entitled to submit a concrete contribution. All the effort which has to be spent to get a CLA signed and maintained is not needed. The only tasks which have to be carried out are:

Since the DCO version 1.1 is the “standard” the “Legal”- and “IP department” only have very little effort to spend.

Procedure for contributions to existing projects

The more complex the business environment in which the code to publish was developed, the more stakeholders need to be involved. The picture below shows a procedure that involves all functions, even in a complex setup.

contributions

Abbreviations used:

The procedure shown above is not suited for frequent contributors and/or contributors who are working “upstream” in their daily work. For these developers different procedures need to be established in order to avoid loading them with “unproductive” work. Different contribution models can be established in an organization to serve different needs.

Contribution models

The following approaches are suited for such developers:

small-contributions

Small contributions model or trivial contributions

A small or trivial contribution is a rather small and simple change to already existing open source software. Typical cases found in this category are bug fixes with no or low Intellectual Property value.

A change is not trivial if:

This procedure scopes small contributions. It can be implemented for small or trivial contributions following the initial contribution to a particular OSS project or component. The initial contribution has to undergo the entire procedure described above, because CLAs/DCOs etc. have to be checked and signed in case the particular project requires them. After the initial contribution all subsequent small contributions can be contributed directly to the OSS project without the need to follow the defined process no matter which version of the OSS project.

Major to major release model

This procedure scopes the release cycle of the OSS project to which contributions shall be made. It has the same “starting point” like any other contribution - the initial contribution must implement the entire procedure in order to check CLAs/DCOs and to have the documented permission to contribute to a specific project. After the initial contribution all subsequent contributions during the development of a new major release can be contributed to the OSS project without the need to go through the approval process. There is no size limitation for contributions. The contributions can range from a trivial bug fix to adding new features, changing interfaces, refactoring and so on. After the release of a major version of the project a new approval procedure has to be kicked off for the first contribution after the major release.

Full trust model

The full trust model can be applied to developers who have already successfully worked under the major to major release model. It is an incentive for the employee and a sign of trust of the employer towards the employee. Basically it is the permission for the developer to work “upstream” without any approval procedure. Since this model shall only be applied after the developer worked successfully under the major to major release model, there is no need for an “initial” contribution with the entire approval procedure, although it makes sense in order to have it documented.

The major to major release model as well as the full trust model shall only be executed by senior developers, who are specially trained in copyright principles, have a good understanding of the business interests of the company they are working for, practice “an ownership culture” and have already deep experience in the open source ecosystem.

In order to track all the contributions the developers shall contribute with their official email address.

Approving projects for contributions

Another model is to provide approval for specific projects. These projects are checked, e.g. by the OSPO, and if everything is in place to allow contributions, they are cleared for contributions by employees. Then there is no individual approval for each specific contribution required. But if the general conditions of the project change, such as license or introduction of a CLA, etc. the project needs to be cleared again by the OSPO

Prerequisite for such a model is that contributors are qualified to do contributions autonomously. This can be achieved by making sure contributors have received training and/or tracking and approving who can contribute to which repository.

Spare-time contributions - also known as “moonlighting”

What to do in case an employee wants to contribute to OSS projects in their spare time which do not fall under the corporate context?

In this case the copyright ownership stays with the developer (assuming they are not developing for another entity). In order to provide clarity the following procedure can be implemented:

The developer informs his or her manager about the intention to contribute to a certain project (which is out of scope of section 69b German Copyright Act). In case the manager has no objections he/she draft a small note with, at least, the following content:

The note can be sent to the HR department to keep it in the personnel record of the employee.

This procedure provides transparency especially in the context of large enterprises, acting in many different software technology areas.

The example below shall illustrate why such a procedure makes sense:

A developer may, for example, implement Linux kernel drivers according to his duties. Another area of interest of the developer is for example AI and the developer wants to contribute to an AI project during his spare time. Given that the AI project has nothing to do with Linux kernel driver development, the developer holds copyright on his contributions and the copyright ownership is not transferred to the employer. The developer can contribute code without the need of an approval by his employer.

But what about when the developer decides to move to another department inside the company, which develops AI. All of a sudden the former “moonlighting” is now covered by section 69b of the copyright act and the copyright owner now is the employer.

The above described procedure provides transparency about the copyright ownership and its change during the time.

Trainings

Contributors to open source projects will need to act with a certain degree of autonomy to be effective. For some corporate software developers it will also be new to participate in open source communities. For these reasons it is important to support corporate contributors and provide them with training or similar means to develop the understanding and skills to act as good citizens of the open source world on behalf of your company.

This can be achieved with mentoring, good practice guides, or trainings which cover the following topics:

Starting open source projects

Motivation

There are many good reasons to start own open source projects. See the introduction for some of the motivations for doing this.

Launching a new OSS project is comparable to a product introduction and it is, at first hand, a software development project - there is no difference to an internal software development project concerning planning, budget, staffing, testing etc. - the only difference is that everything happens in the public area. Be aware that publicly available source code is the “business card” of the organization to the software ecosystem, and it is also the “business card” of its maintainers.

When thinking about to start an own OSS project there are several phases you should consider:

oss-project-process

Project life cycle

The life cycle of an open source project describes the stages in which the project evolves, from its conception to its retirement or end of life stage. Typically, a project originates to solve a specific problem. It may become obsolete either because the problem does not exist anymore or because other projects are better suited to solve the problem. The figure below shows the different stages an open source project may undergo.

Typical lifecycle of an open source project

Planning or Concept Phase

This is the starting point of every open source project. It can also be referred to as the “initiation phase”. Normally, at this stage, only an idea exists or a specific problem has been identified which requires solution. In this phase, the open source project typically has the following characteristics:

Before starting a project, it is reasonable to get answers to the key questions:

(Source: Linux Foundation)

In addition, the following aspects should be considered in the planning phase:

Active or Development Phase

Once the project has got an approval for open sourcing and the code is available and published, the project has entered the active development phase. In this phase, the open source project typically has the following characteristics:

During the active phase, the following aspects should be considered:

Mature or Maintenance Phase

At a certain point in time, an open source project becomes mature. This can also be referred to as the “maintenance phase”, meaning that only error corrections are made and normally no new functionality is developed. The following aspects characterize this phase:

Obsolete or End of Life Phase

An open source project in this phase is characterized by the following properties:

During this phase, it is important to consider the legal implications and come up with the appropriate documentation and communication with the community. Since the project has been published, it might be in use. Therefore, the community needs to be informed that the project is no longer maintained. Furthermore, once in this phase the decision must be made whether to archive the project or remove it completely.

Which license to select

Choosing the license for a new open source project is an important decision. Without a license the code can’t be used by anybody, even if the code is publicly available, for example in a GitHub repository. Choosing a license which is not approved by the OSI as an open source license also effectively makes the code proprietary. This will make it harder to get adoption, especially in most corporate setups, where processes are usually built around the well-known standard open source licenses.

Open source licenses vary in the rights and the obligations they give to users. All open source licenses approved by OSI give users the right to use the software without restriction to specific users or use cases. When distributing open source software, and especially when distributing it with modifications, the obligation vary. The spectrum goes from the so-called copyleft licenses such as the GPL, which require to pass on rights given by the license to users, to permissive licenses, such as the Apache or the MIT license, which allow incorporation in proprietary systems.

When choosing a license the following questions have to be considered:

Answering these questions can be challenging and opinions will vary. A simple starting point can be the choosealicense.com. There is a lot of comprehensive material available from various sources, e.g. Open source licenses: What, which, and why.

It is advisable to set up policies for license selection, so that the decision process is simplified when starting new projects.

Contributor License Agreement (CLA), Developer Certificate of Origin (DCO)

When running an open source project you need to decide how you are going to check code provenance and if you need additional rights from contributors which are not given by the license. There are mainly three ways how to handle that:

You should have a policy for which of these ways you use when. “Inbound=Outbound” is a pragmatic way which can work for most projects. The DCO is a good way to make the contribution process more explicit, especially for larger projects with diverse contributors. The CLA makes contributions more difficult and requires additional administrational work and tooling. To get an impression about the additional effort and difficulties especially large corporations face you can check the section about contributions to existing projects.

Project governance

An important factor for the success of an open source project is its governance. That comprises the rules, policies, conventions, and culture of the collaboration. It determines factors such as how decisions are taken, who is in control, or who can join a project.

In existing projects governance often has emerged over time, has gone from informal procedures driven by the practices of the project founders to more formally defined governance documented in contribution guides or ultimately instituted through a foundation as formal organization hosting the project.

When starting a new open source project you have to decide about how its governance will look like. This goes beyond deciding on a license. You will also have to decide about ownership of assets such as trademarks or domains and the rules how they can be used. And you will have to decide about policies of how people can become committers or maintainers, how releases and roadmaps are made, or how transparent the decision making process is.

For a project which is meant to attract a broad set of contributors it is important to set up governance which provides a neutral ground, is open to participation by diverse participants, and is transparent about its decision making. This can be called open governance. One way to achieve this is to join one of the existing open source foundations. Prominent examples for this are Kubernetes which is hosted by the CNCF or the Eclipse IDE which is part of the Eclipse Foundation.

In other cases a company might want to retain more control about the project. This will limit contributions from others but give more freedom in how to steer a project. It requires that there are enough resources allocated to maintain the project. It still is helpful to implement elements of open governance, such as transparency about planning or a permissive trademark policy to increase adoption of the project. Examples for this would be TensorFlow which is run by Google or Visual Studio Code which is run by Microsoft.

For smaller projects, for example technical tools which emerge from work on other projects, a simple and less formal approach to governance can also work. Here the goal is not primarily broad adoption or building a large community, but transparency and ad-hoc collaboration with interested individuals. Often this kind of project is more driven by technical needs and motivation of developers than by overarching business needs. If such a project is growing its governance can be evolved. This can for example result in a project being transferred to a foundation. Countless examples can be found on GitHub.

More detailed information and possible starting points for open source governance can be found in the Minimum Viable Governance framework or A Legal Issues Primer for Open Source and Free Software Projects.

Different Project Levels

It can make sense to have different levels for new open source projects (“sandbox”, “incubator”, “graduated” - these are the different project levels of CNCF, for example). This is a way to classify your open source projects wrt. adoption, maturity and quality criteria that they have to fulfill. The basic idea is that new projects start in a dedicated space (CNCF calls that “sandbox” - at Meta, that’s the “Incubator”). In this space, projects can evolve and check if they reach the goals that have been defined in terms of adoption and quality. If they do, they can be promoted to the next level. If they don’t, it might be decided to sunset them.

Community management

For the majority of open source projects, starting a community around that project and receiving contributions is an important if not the primary goal (however, there are also projects where the primary goal for open sourcing is not the creation of a vivid community - for example building trust by making the source code visible, in this case receiving contributions might have a lower priority). Such a community does not take off by itself. Starting it and keeping it alive requires planning as well as budget and resources. Initial and ongoing activities comprise:

It’s advisable to assign a community manager to the project who takes care of these tasks. The TODO Group Guide Starting an open source project contains more information in its chapter “Build the community”. For further reading, we recommend the TODO Group Guides Building an inclusive open source community and Building leadership in an open source community.

Code of conduct

Creating a welcoming environment where people are safe from harmful behavior by others is an important part of maintaining a healthy community. It is especially important to support a diverse community, where there is no discrimination of under-represented groups, and explicit or implicit bias gets addressed.

A common element in maintaining a healthy community environment is a code of conduct which makes rules for accepted and unaccepted behavior explicit and defines how unacceptable behavior is dealt with. There are examples and templates which can be used as a base for your code of conduct. One popular reusable code of conduct is the Contributor Covenant which is used by projects such as Kubernetes, git, Node.js, and many more.

As a company you need to provide a contact email which can be used to report code of conduct violations. You need to make sure that this address is monitored by people who can react in a timely manner and have the competence and ability to initiate adequate actions to address these issues.

Technical considerations, tooling and best practices

Appropriate tooling can safe a lot of time and help to automate processes significantly. Curated list of awesome tools to manage open source contains a comprehensive list of proven and recommendable tools.

User management

Normally, Git providers (GitHub, GitLab, Bitbucket etc.) offer means to define teams of individual users and to define (access) rights on team and on individual level. To be able to use the service of a Git provider, engineers have to create a corresponding account. This account has nothing to do with the company-internal account of an engineer. This imposes some challenges since the access rights of an engineer for an external repository might depend on their role in the company or whether they are still working for the company (let’s assume that an engineer got comprehensive rights for external repositories when they were working for your company and that they now left the company - you might want to adjust the access rights). But how to do that since the external account of an engineer at a Git provider is independent from his company-internal user account? Somehow a mapping between both accounts is needed. For GitHub there’s the open source tool opensource-portal available that can help to create such a mapping. It can also be used to implement a self service for joining of GitHub organizations. As part of the process, the tool creates the mapping between the GitHub.com account and the corresponding company-internal user account. The mapping is stored in a database. Based on this, it is easy to create some tooling that regularly checks if all users that are contained in that database are still employed by your company and trigger some activity if that’s not the case.

Setting up a repository

It is good practice that a repository contains a certain set of files (the health files). These files contain the basic information about the repository such as description, code of conduct, license, contribution guidelines etc. These files are often provided in markdown format, but could - depending on the Git provider - be provided in different formats such as AsciiDoc. Here, we assume the default format (which is markdown) and thus use the file suffix .md.

The README.md and the license text file should be there for all repositories. The other files can be considered as optional and only be created if they are required (if, for example, no contributions are accepted, this information could be put into the README.md and a CONTRIBUTING.md is not necessary).

To make sure that a certain set of health files is always created, there are different possibilities:

License and copyright information must be declared properly for an open source project. This is important for consumers of the project as well as for contributors. Furthermore source code often gets copied from one project to another, this makes it mandatory that all files carry license and copyright information

Note that a statement like For license conditions please check LICENSE.txt is not suited.

The REUSE tool from the Free Software Foundation Europe supports the proper declaration of license and copyright information for your project:

CLA/DCO Management

If contributors must accept an CLA or DCO before they can submit their contributions, it is beneficial to automate that process as much as possible. The TODO Group provides a list of tools that support the management and the sign-off of DCOs or CLA documents. As an example, we describe the CLA Assistant in more detail.

The CLA Assistant implements a workflow that asks contributors to accept/sign-off a document when a contributor submit the first pull request to a certain repository on GitHub.com. Despite the name of the tool (“CLA Assistant”), it can be used for any type of document that companies require contributors to accept before a pull request can be submitted, including CLAs and DCOs. The document text must be provided as gist on GitHub.com. Which document/gist to be used can be configured on organization and on repository level. The CLA Assistant uses a default logic: If for a certain repository no specific document is configured, the document that is configured on organization level is used. When a contributor submits a pull request for a repository for the first time, the CLA Assistant displays the document text and the contributor can only submit the request if they accept the document. The next time, the same contributor submits a pull request, they can do so without having to accept the document again. The information that the contributor accepted the document for that repository is stored in the database of the CLA Assistant and can be retrieved later on. The CLA Assistant is available as hosted offering on https://cla-assistant.io/ or can be self-hosted.

Credential scanning

Even if open source policies and guidelines explicitly require that credentials such as password, access tokens or other secrets have to be removed from code before it is published, it happens from time to time that unintentionally such important and sensitive data is pushed to public repositories. To detect such situations as quickly as possible (and thus to be able to revoke the published secret and remove that data from public repositories), it is advisable to regularly execute credential scans for such repositories. Luckily, all well-known code hosting platforms (GitHub.com, GitLab.com etc.) provide such scanning services as part of their offering. We strongly recommend to use that services.

Quality criteria / CII Best Practices Badge Program

The Core Infrastructure Initiative (CII) created the CII Best Practices Badge Program. It is now continued by the Open Source Security Foundation. As part of the program, best practices for open source software is defined and a badge system is implemented. Via a web app, projects can self-certify that they meet the criteria and show a corresponding badge on their website. As of today (May 2022), more than 4724 projects did the assessment.

The CII system consists of three levels (Passing, Silver and Gold). They are building on each other (i.e. the Silver level contains all criteria of the Passing level plus additional ones). The criteria are structured in clusters such as Basics, Change Control, Reporting, Quality, Security and Analytics.

The CII Best Practices Badge community is open for contributions (additional criteria, for example).

Overall, the CII Best Practices Badge Program is a good means to verify own projects against commonly accepted best practices. Via the badge, projects can document that they meet these criteria.

Repository Linting

Repository linters are tools that check in an automated way if repositories adhere to the guidelines that a company has defined for its public open source repositories. The TODO Group provides a list of tools that can be used for this purpose. Typically, repository linters check criteria such as:

However, which criteria they check is company-specific and thus, they normally provide the possibility to configure rules (as JSON file, for example, as the repolinter of the TODO Group does). To retrieve the necessary data to execute these checks, the APIs of the Git provider (GitHub.com, GitLab.com, Bitbucket.org etc.) is used. The result of the check is typically provided in a UI. Another option is to automatically create issues in the corresponding repository if checks fail. Typical usage scenarios for such a linter include:

Build an open source metrics strategy when releasing to open source projects

Once you have established the goals, procedures, and tools for your company’s outbound open source plan, it is always useful to monitor and track the overall health of open source projects the company engages with as they grow and mature.

Before thinking about which tool should be used to track project health, a good alternative on how to do this is to establish a full metrics strategy following the goal-question-metrics approach. This approach is used in communities focused on community health analytics metrics standards and software, such as CHAOSS, one of the projects under the Linux Foundation umbrella.

Defining community health goals

Sometimes it is better to start small and define two or three main goals first before getting overwhelmed by metrics. If you don’t know where to start, CHAOSS offers a set of metrics based on different focus-areas and goals when measuring project health that can help you get started in measuring the health of the open-source projects that matter to your organization:

Creating questions and building metrics around

Metrics should be answering specific questions that are aligned with the previous goals established.

For instance, if one of your company’s goals is to understand the community footprint within a project, one good question can be “What’s the presence and influence of organizations within the open source ecosystem?”. In order to solve this, one useful metric can be the Elephant Factor (the minimum number of organizations whose employees perform 50% of the total contributions).

There are great tools to help you measure different community health analytics metrics, for instance, GrimoireLab, LFX, or Augur.

For further information about tools for tracking project health, check this dedicated section from one of the TODO Guides

References and Abbreviations

Abbreviations

References

Appendix

Managing work vs personal emails in git

In the world of open source, folks may have an online identity that pre-dates their employment with our current organization. Simultaneously, the organization may want contributions done on their behalf to happen with corporate emails.

One way that folks can solve this is by encoding their commit email on a per-repository basis, like:

git config user.email "simba@special-email.example.com"

If you work with several repositories, this will become difficult to manage and easy to forget. Instead, we can use a feature of git which allows different configurations based on our directory structures.

Our ~/.gitconfig file might look like this:

[user]
	name = Simba Lion
	email = simba@personal-email.example.org

[includeIf "gitdir:~/my-company/"]
    path = ~/my-company/.gitconfig

This sets our default email (which, in this case, is for a personal account). If we have repositories in the ~/my-company directory, we’ll load an additional git config file which is located at ~/my-company/.gitconfig. That file might look like:

[user]
	email = simba@very-corporate-email.example.com

Now when our user commits changes, it will use their personal email by default, or their corporate email for any repositories within the ~/my-company folder. Note that the name attribute is inherited from the base configuration, so we don’t need to double specify it.