DRAFT work in progress

Akraino Best Practice for Upstream Dependencies

Akraino community consists of three types of projects, Feature, Integration (aka Blueprint) and Validation. 

For Blueprints, the corresponding project is typically based on one or more upstream open source projects outside of Akraino. Akraino community (see the community document) adopts a "Upstream First" philosophy and encourages bug fixes or feature additions be contributed back to upstream first in order to reduce technical debt and avoid forking. Exceptions are allowed but must have clearly identified reason with TSC approval.

For Validation projects, we may utilize software tools, testing frameworks or test suites from upstream open source projects. In these cases, the best practice should also follow the same principle as in the Integration projects.

Akraino Feature projects develop original source code that is not adopted from upstream directly. These projects may also base their foundation on other open source projects or utilize upstream tools or frameworks. In all these cases, the same principles apply.

The Coordinators

For all three types of projects in Akraino community :

• A project may name an upstream "Coordinator" or several projects may name a common upstream "Coordinator" for a given upstream community.
• The Coordinator should declare and document explicitly the most relevant upstream open source projects that the project depends on, including multiple layers if applicable, and document how these upstream components are used within the project. This information shall be made available with consistent documentation and consolidated for easy access by the Upstream Sub-committee.
• The Coordinator is responsible to work with the corresponding upstream projects, as a liaison, in order to meet Akraino best practice requirements (that will be developed by this Sub-Committee, see next item.)
• The Coordinators should work within the Upstream Sub-committee meeting to report status, resolve issues, and document best practices.
• The Coordinators can share their roles as the liaison to a common upstream project.

The Best Practice

The Upstream Sub-committee should develop a current best practice policy that all projects can follow.

• NOTE: some aspects of these policies should fall under other sub-committees, such as process, CI/CD etc, but the projects/coordinators should probably formulate these in practice.

This policy can be evolved and improved over time. We will start with a draft, e.g.

• All important upstream projects should identified, and its usage (architecture, design or other aspects of dependencies) clearly defined.
• Bug reports, fixes, new features additions, etc. should be visible in its whole lifecycle, from reporting, discussion, resolutions.
• Projects should define an explicit upstreaming process
  • Upgrade cadence
  • Version
  • Bug/feature reporting tool (e.g. Jira, github) address or dashboard
  • Testing linkage
  • CI/CD linkage
• Synchronization methodology
  • If there is non-merged code, describe the reason and bring an exception request first to the Upstream Sub-committee for a technical review. If the Sub-committee concurs, then bring to TSC for approval.

Documentation

• The Upstream Sub-committee should make the above information accessible by appropriate format of documentation.
  • Produce a document format that all projects can contribute into a single document.
  • Produce a summary that can be shared with other communities.

Single Point of Liaison

The other role that TSC assigns to the Upstream Sub-committee is to be the single point of liaison to other communities and organizations. These may include upstream projects who want to know more about Akraino overall (rather than a specific project within Akraino), or larger open source communities and other industry or standard organizations interested in interactions with Akraino beyond a single project and in more stable long term arrangement.

Initially, the Sub-committee plan to initiate a series of talks by relevant organizations that overlap with Akraino's mission. For example, Openstack Edge working group, Kubernetes edge working group, ONF, ONAP edge working group, EdgeX (and other LF Edge projects), TIP, and ...

The Ambassador

We recommend that the Upstream Sub-committee act as an ambassador (See community technical document description of this role), but meetings can take place in any community meeting slots as appropriate, e.g. in the community meetings, in TSC meetings, but can also be hold during this Sub-committee meetings. All such meetings material should be consolidated into one place in the Upstream Sub-committee wiki and documentation for easy search and access.

Similarly, the Upstream Sub-committee will also represent Akraino community in the reverse direction to these and other organizations on behalf of Akraino.