Category: Cloud

To recap, there are three dimensions to participation in open-source software:

• Consumers, who study or use the repositories of others.
• Contributors, who are actively involved in the improvement of the repositories of others.
• Producers, who build and maintain their own repositories that are open to others.

As organizations think more deeply about what they want to get out of each dimension, it’s a good practice to take stock of where they are today. There are five process levels within each dimension.

 

• Ad hoc, which have no process in place. Success depends on individual efforts.
• Managed, which have a partially documented process. Success depends on discipline.
• Defined, which have a documented, standardized, and integrated process. Success depends on automation.
• Measured, which a quantitatively managed process. Success depends on measuring metrics against business goals.
• Optimized, which have a process that is continually and reliably improving through both incremental and innovative changes. Success depends on reducing the risk of change.

To get a better understanding of where your organization stands, check out the best hosting

What should you open-source?

Many projects are not destined for open-source greatness. While your criteria may vary based on your company’s goals and process level, here are some recommended criteria to consider before open-sourcing a project:

• Does your project contain intellectual property that you want to protect? If so, then opening its source would give away its value. Do not open-source those kinds of projects unless you feel the benefits outweigh the risks.
• Is the project in a stable state with good code quality? The project doesn’t have to be perfect, but potential contributors may walk away if the project is in terrible shape to begin with.
• Is your project useful to people outside of your company? If not, then you probably won’t get any participation.
• Will people outside your company be able to contribute? They will need access to all project dependencies, build processes, and whatever else is needed to run the project. If they can’t run it, then they can’t contribute.
• Does your team have the bandwidth to support an open-source program? If not, then wait until you do. If you open-source a project and then don’t support it, you might lose your opportunity to build a trusting community.

These questions are just a few of the most common considerations. Your organization may have additional business or compliance issues to keep in mind.

Designing an open-source program

Running an open-source program is similar to running an InnerSource program, but for a public audience. As a result, there are a few additional considerations.

Setting community expectations

Files like README.md and CONTRIBUTING.md are even more important because they are being exposed to people who don’t have your organizational context. They will need to be evaluated from the perspective of someone outside the company to ensure clarity.

In addition, your code of conduct is an important policy to express. The standard is to add a CODE_OF_CONDUCT.md file to the root of your repository and use it to explain the behavior expected from participants in your community. This document should be reviewed by multiple groups in your organization, including your legal team. Fortunately, there are many standard codes of conduct available to start from. Many projects use these codes as-is without modification. Learn more in the Guide to open-source codes of conduct .

Preparing employees to maintain a repository

Employees may not have experience working with the open-source community. To help them prepare, it is recommended that the company offer a set of guides the cover the key things everyone should know before they get started. These guides should be posted to an internal repository or portal that is only accessible to company employees and regularly maintained. A few of the most important guides are listed below.

• A “Should we open-source this?” guide that provides a framework for deciding whether or not a candidate project should be open-sourced. This guide could be structured as a flowchart, set of questions, or list of considerations.
• A setup checklist that includes all of the work items a team needs to complete before and after the launch of an open-sourced project. This list should include acquiring approval to open-source the project, code reviews to ensure sensitive data is removed before the project goes live, a trademark or open-source project search to ensure there isn’t a naming conflict, and so on.
• A contact list for key people in your organization that may need to be contacted in a hurry if something goes sideways. This list should include people from software security, site security, legal, public relations, and so on.
• A link to a starter repository that can be cloned as a starting point. It should contain a sample README, license, code of conduct, contributing guide, and any other supporting files every open-source project from your company needs to have. It shouldn’t contain anything you wouldn’t want accidentally pushed to a public audience.
• A maintainer’s guide that explains the responsibilities a maintainer has in keeping the repository healthy. These responsibilities will include keeping repository documentation up to date, ensuring issues and pull requests get the attention of the right people in a timely manner, and so on.
• A communications guide that offers repository maintainers guidance for some of the topics you would prefer not to include in public files like README.md, CONTRIBUTING.md, or CODE_OF_CONDUCT.md. These subjects may be sensitive business topics, such as not discussing competitors, or more general conduct topics, like how to appropriately recognize top contributors.
• An internal FAQ that provides approved answers to common questions. This list is especially useful if there are legal subtleties to the topics your company may discuss in the course of maintaining an open-source program.
• A license policy that lists which licenses have been approved or rejected by the legal department for open-source consuming or contributing.

What is InnerSource?

InnerSource is the practice of applying open source patterns to projects with a limited audience. For example, a company may establish an InnerSource program that mirrors the structure of a typical open source project, except that it is only accessible to the employees of that company. In effect, it’s an open source program behind your company’s firewall.

InnerSource benefits

An InnerSource program can offer numerous benefits beyond what traditional closed source models provide.

First, they encourage transparency. Access to the source code of other company projects can help developers be more productive when working on their own projects. They can see how different teams solved problems similar to the ones they’re facing, and often find code and other assets that can be reused. Access to team issues, pull requests, and project plans also provide better data for them to understand the velocity and direction of the project.

Next, they reduce friction. If a consumer team is dependent on a bug fix or new feature for a project owned by a different team, they have a channel through which they can propose the changes they need. And if those changes cannot be merged in for any reason, the consumer team has the option of forking the project to meet their needs.

Finally, they standardize practices. A common challenge development organizations face is that different teams often diverge in the ways they operate. Building an InnerSource program is a great opportunity to adopt standard conventions that can be leveraged across every development team, even if they don’t follow identical practices. For example, two teams may prefer different processes for accepting contributions. Having them standardize on the way they communicate their different processes makes it much easier for anyone to contribute to either.

These examples are just a few of the benefits enjoyed by InnerSource programs. To learn more, see An introduction to InnerSource .

 

Setting up an InnerSource program on GitHub

Setting repository visibility and permissions

GitHub repositories can be configured with three levels of visibility. Users who do not meet the visibility requirement will see “not found” pages when trying to access your repository. The levels are:

• Public repositories are visible to everyone. Use this visibility for projects that are truly open source and offer access to people inside and outside of your organization.
• Internal repositories are only visible to members of the organization that owns them. Use this visibility for InnerSource projects.
• Private repositories are only visible to the owner and any teams or individuals they add. Use this visibility for projects that should only be accessed by specific users and groups.

 

Once you have established repository visibility, you can configure permissions on an individual or team basis. There are five permission levels:

• Read level is recommended for non-code contributors who want to view or discuss the project.
• Triage level is recommended for contributors who need to proactively manage issues and pull requests without write access.
• Write level is recommended for contributors who actively push to the project.
• Maintain level is recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
• Admin level is recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository.

Learn more about repository access permissions by level .

Creating discoverable repositories

As an InnerSource program grows, the number of repositories will likely scale up significantly. While it’s great to have all these assets available to the organization, it can become a challenge to efficiently find content. To proactively address this issue, it is a best practice for teams to consider what they can do to make it easier for others to find and work with their repositories.

A few best practices include:

• Use a descriptive repository name, such as warehouse-api or supply-chain-web.
• Include a concise description. A sentence or two should be enough for potential users to know if the project might fit their needs.
• Include a README.md file in the root of the repository. This file is used by GitHub as the landing page when people visit the repository.
  • Articulate the purpose and vision of the project so potential consumers understand whether it fits their needs.
  • Offer visual aids, such as screenshots or code samples, to illustrate the project in action.
  • Include a link to a production or demo version of the app for review.
  • Set expectations for prerequisites and deployment procedures. If the project has disqualifying prerequisites, then let potential users know early.
  • Include references to projects you depend on. Visitors may only need to use one of the projects you depend on to meet their needs, and this will save everyone time. It’s also a good way to promote the work of others.
  • Make use of Markdown to guide readers through properly formatted content.

Check out some Awesome README examples .

Once the project has launched, use email and other networking channels to promote it. Reaching an appropriate audience could produce a significant boost in project participation.

Managing projects on GitHub

As projects gain traction, the influx of users and contributions can require a lot of work to manage. Depending on the project, a significant amount of work may be required just to manage the expectations of project participants.

To proactively address this, GitHub looks for a CONTRIBUTING.md file in the root (or /docs or /.github) of a repository. Use this file to explain the contribution policy for the project. The exact details may vary, but it’s a good idea to let potential contributors know what conventions the project follows, where the team is looking for pull requests, what details are requested for bug reports, and so on.

 

Creating issue and pull request templates

GitHub supports starter templates for new issues and pull requests. Use these to provide the initial description text for a newly created issue or pull request.

For example, if your project has .github/ISSUE_TEMPLATE.md, anytime a user starts the process of creating an issue, they will see this content. Rather than having to constantly reference the required details from a CONTRIBUTING.md, they’ll be able to just fill out the issue like a form using the template text.

cc

 

It’s the same for pull requests, except that the path is .github/PULL_REQUEST_TEMPLATE.md.

Check out some Awesome GitHub issue & pull request templates .