Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add link to contributions kanban board.

Table of Contents

Overview

Before the Foundation is able to host an open source project, it must go through a contribution gate.  During this process we validate that:

  1. The code is legally ready to be hosted.
  2. The project is "in scope" for the Foundation.

Note that the Foundation does not place any technical, security or quality requirements on projects at contribution time - those requirements are introduced later in the project lifecycle.  The code could be incomplete, non-functional, non-buildable, or even non-existent (i.e. the contribution is just a project idea), and the project can still be incubated with the Foundation.

All new contributions must go through this process, even if the contributor has existing projects hosted with the Foundation.

Initiating a Contribution

Anyone may initiate a contribution to the Foundation, whether they have previously engaged with the Foundation or not, and regardless of the level of maturity of the contributed code (if any).  This involves creating a Project Contribution issue in the Foundation's JIRA instance, using the description template below.  If you do not have an account on JIRA, you can sign up here.

Project Contribution Description Template

All new Project Contribution JIRAs should use the following template for descriptions - doing so greatly facilitates the contribution process.  Please use hyperlinks liberally when referring to external sources of information.

Code Block
languagetext
titleProject Contribution JIRA Template
collapsetrue
h4. Background
<_Describe in a couple of sentences why this project is needed - the business problem the contribution solves, the market conditions that make open source a compelling approach, etc._>

h4. Proposal
<_Describe what the project does or proposes to do - how it addresses the business problem, what business model will be used (if any), how it will be implemented, etc. Be liberal in including technical details (languages, platforms, 3rd party components, deployment model etc.)_>

h4. Rationale
<_Describe why this business problem is worth addressing, and why the proposed solution is the best way to address it._>

h4. Current State
<_Summarize the history of the project, and describe the current state._>

h4. Near Term Goals
<_List out a set of near term goals / roadmap items. These should be missing capabilities and/or bugs that have been identified as "must haves" in order for the project to be minimally viable. If the project is already minimally viable, you should indicate as such._>

h4. Future Goals
<_List out any speculative future goals / roadmap items that might be on your radar. Feel free to leave this section blank if it's not relevant._>

h4. Issues / Risks
<_List out any issues or risks you've identified for the project. The intent here is to give the Foundation a head's up on areas where they can actively solicit assistance from the wider community. Feel free to leave this section blank if it's not relevant._>

h4. Code and Core Developers
h5. Current SCM:
<_URL(s) of the current SCM repository(s) for the code, if they exist and you're able to share them._>

h5. Code Transfer Approach:
<_How you'd like the Foundation to [transfer existing code|https://symphonyoss.atlassian.net/wiki/display/FM/Contribution#Contribution-CodeTransfer], if there is any._>

h5. Desired GIT Repository Name(s)
<_All lowercase with '-' character as word separator.  If your project is made up of multiple repositories, please list all of your desired names.  Note that the Foundation will do its best to use these name(s), but cannot guarantee they will be used verbatim in all cases._>

h5. Owners:
* <_List of initial project owners, including their full name, Github user id, and affiliation.  These users will be given GitHub "admin" access to the project's repository(s)._>

h5. Committers:
* <_List of initial committers, including their full name, Github user id, and affiliation.  These users will be given GitHub "write" access to the project's repository(s)._>

h5. Do you require access to the [Open Developer Platform|https://symphonyoss.atlassian.net/wiki/display/FM/Open+Developer+Platform] (for unit testing and continuous integration & delivery)?
<_Yes / No_>

Approval Process

Once submitted, the Foundation will run the Project Contribution through the following steps:

  1. Validation of all legal requirements.
  2. Approval to accept the contribution - this is performed by the Engineering Steering Committee (ESCo), representing the Foundation.
    • The focus of this review is to ensure that the project has a good "fit" with both the charter of the Foundation and the existing portfolio of projects.
    • The ESCo's voting rules are used for this approval, and the vote is typically conducted on the ESCo's private mailing list, with the result publicly recorded in your Project Contribution JIRA.  Any feedback is provided directly to the contributor by individual ESCo members, allowing a free and easy exchange of information.


Info

To date, the Foundation has found that validating the legal requirements tends to take substantially longer to complete than any other step in the process; specifically, obtaining a signed contributor agreement typically takes weeks to months.  It is therefore recommended that potential contributors start working towards having a signed contributor agreement in place as soon as possible, without necessarily waiting for a contribution to act as a trigger.  Contributions that are made with a contributor agreement already in place are substantially faster to complete than those without.


Code Transfer

Once the Project Contribution is approved, existing code (if any) can be transferred to theFoundation's GitHub organization.  We are flexible as to how this is done, but here are a few of the approaches that have worked well in the past.  Please indicate which method you wish to use in your Project Contribution JIRA, along with a good date & time to perform the transfer (this information can be added later, for example after the approval process has concluded).

Source(s)Approach
GitHub.com repository

Use GitHub's transfer ownership capability to move it over to the Foundation's GitHub organization. To do this you will need to temporarily add the Foundation's ssf-admin GitHub user as an admin on your repository, so that we can initiate the transfer (once the transfer is complete, you will be able to remove ssf-admin from your repository - in fact we encourage you to do so).

The Foundation recommends this approach as it has the unique benefit of preserving the full commit & pull request histories, the project's issue list, wiki and GitHub pages, and more.

Some important notes:

  1. When you transfer a repository, its issues, wiki, stars, and watchers are also transferred (read more details about repository transfers)
  2. When you transfer a private repository, all forks will be disabled, until marked as public ; they will also be disconnected from the upstream repository, therefore it is strongly advised to push all changes to an upstream branch, before performing the code transfer
GitHub.com repository where it is not possible to temporarily configure ssf-admin as an admin

Perform a double transfer:

  1. Transfer ownership of the repository to your own personal ("user") account on GitHub (see the GitHub documentation for details)
  2. Follow the steps described above for transferring a GitHub.com repository to the Foundation

GitHub Enterprise repository

Perform a copy, transfer, and freeze:

  1. Copy the repository into your own personal ("user") account on GitHub (this StackOverflow post describes how to accomplish this)
  2. Follow the steps described above for transferring a GitHub.com repository to the Foundation
  3. Delete or freeze (e.g. disable access, make read-only, etc.) the repository in your GitHub Enterprise installation, to prevent accidental modifications to the wrong repository.
Other Source Code Management (SCM) repository

Perform an import, transfer, and freeze:

  1. Use the GitHub importer to import the repository into your own personal ("user") account on GitHub (see the GitHub documentation for details)
  2. Follow the steps described above for transferring a GitHub.com repository to the Foundation
  3. Delete or freeze (e.g. disable access, make read-only, etc.) the repository in your SCM installation, to prevent accidental modifications to the wrong repository.
Source code snapshot

We can also accept a single archive file (.zip, .tar.gz, etc.) containing a snapshot of your source code. Please attach the archive file to your Project Contribution JIRA and we will import it right after we create your repository.

This is the recommended approach if you wish to truncate the commit history prior to contribution.

None / DIYIf you do not have any existing code to transfer, or wish to populate it yourself, we will be happy to create an empty repository in the Foundation's GitHub organization, and configure the owners and committers listed in the Project Contribution JIRA. You can then prepare an initial commit at your leisure.

Accepting GitHub Invitations

Following completion of the code transfer, we will invite your nominated admins and contributors to the GitHub repository.  Your team must accept these invitations before they will be able to write to the repository!

This is done by accessing the following URL (substituting the name of the GitHub repository for <repository-name>), and then accepting the invitation:

https://github.com/symphonyoss/<repository-name>/invitations


Info

Although GitHub will send you the invitation via email, we've found that these emails are often time-delayed (by days, in some cases) and can be flagged as spam by some email systems.  As a result, we strongly encourage all teams members to pro-actively accept the invitations directly on GitHub.


Current Contributions

The status of current contributions can be seen on this JIRA board.