Add LFN principles and LFN project lifecycle docs.
This change combines work from 10223, 10221 and 10103 to make the
editing workflow easier. Also, these documents are closely related
changes that need to be worked on and merged together, not atomic
changes that should be handled in smaller commits.
Board approval: https://lists.lfnetworking.org/g/TAC/message/420
Change-Id: I84d362a6b6f42fd7f269f7d7a44199355e4fa9f4
Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
Signed-off-by: Ed Warnicke <hagbard@gmail.com>
Contents:
.. toctree::
- :maxdepth: 3
+ :glob:
+ :maxdepth: 4
+ :caption: Table of Contents
+ :name: mastertoc
- governance/charter.rst
- governance/CHANGELOG.rst
- recommendations/index
+ **
Indices and tables
==================
--- /dev/null
+*********************************************
+Linux Foundation Networking Project Lifecycle
+*********************************************
+
+Introduction
+------------
+
+The Linux Foundation Networking umbrella consists of multiple projects. This
+document describes the lifecycle of those LFN projects.
+
+Each LFN project governs itself. LFN projects may consist of multiple
+subprojects with their own lifecycles. This document's scope is limited to
+top-level LFN projects.
+
+Project Lifecycle
+-----------------
+
+LFN projects have a lifecycle. That lifecycle is characterized by Project
+States and State Transitions.
+
+Project States
+==============
+
++---------------+-------------------------------------------------------------+
+| Project State | State Summary |
++===============+=============================================================+
+| Non-LFN | Project does not exist or exists outside of LFN. |
++---------------+-------------------------------------------------------------+
+| Non-TAC | Project is admitted to the LFN but does not have a |
+| | representative on the TAC. |
++---------------+-------------------------------------------------------------+
+| TAC | Project is granted TAC representation. |
++---------------+-------------------------------------------------------------+
+| Archived | Project is no longer active. |
++---------------+-------------------------------------------------------------+
+
+Project State Transitions
+=========================
+
++--------------+-------------------+----------------------+-------------------+
+| From State | To State | TAC Review | Board Review |
++==============+===================+======================+===================+
+| Non-LFN | Non-TAC | LFN Entry Review | LFN Entry Review |
++--------------+-------------------+----------------------+-------------------+
+| Non-TAC | TAC | TAC Admission Review | |
++--------------+-------------------+----------------------+-------------------+
+| * | Archived | Archival Review | |
++--------------+-------------------+----------------------+-------------------+
+| * | Non-LFN | LFN Exit Review | LFN Exit Review |
++--------------+-------------------+----------------------+-------------------+
+
+Project Reviews
+===============
+
+For each review, the project must instantiate the Project Data Template. If the
+project has already submitted a template for a past review, they can update it
+(taking in to account any changes to the base template) for the new review.
+
+Additionally, a project must publicly announce their intention to undergo a
+review at least two weeks prior to the date of the review. The announcement
+must include a link to the instantiated Project Data Template for the review.
+The public may comment on the document. The project must engage with comments,
+answer questions and address feedback.
+
+Reviews must be conducted in a manner that allows a global community to
+participate. For example, at a time that is amenable to as many stakeholders as
+possible and using tooling that is generally accessible.
+
+LFN Entry Review
+****************
+
+The Board and the TAC both review proposals for new LFN projects.
+
+TAC LFN Entry Review
+++++++++++++++++++++
+
+Review by the TAC for creating new projects under the LFN or admitting existing
+non-LFN projects into the LFN.
+
+TAC LFN Entry Reviews should happen before, and provide input into, Board LFN
+Entry Reviews.
+
+Required Information for TAC LFN Admission Review
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An up-to-date instantiation of the Project Data Template is required for an LFN
+Entry Review.
+
+Criteria for TAC LFN Admission Review
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mandatory criteria for successful completion of the LFN Entry Review is
+documented governance that is clear, complete, and easily and obviously
+accessible (such as a link from of the project's main page). That governance
+must minimally specify:
+
+* Project Roles.
+* How people come to fill project roles.
+* How people are removed from project roles.
+* Who currently fills all project roles.
+* How disputes are definitively resolved (usually by majority vote).
+* How the governance evolves over time.
+* What is the top level technical decision making body for the project,
+ analogous to a TSC, to which the TAC should look for interfaces.
+
+Outcome for TAC LFN Admission Review
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As an outcome of the TAC's LFN Entry Review, the TAC will provide the following
+feedback to the LFN Governing Board for use as input to the LFN Board's LFN
+Entry Review:
+
+* Summary of findings
+* Recommendation to accept the project into LFN or not.
+
+Board LFN Entry Review
+++++++++++++++++++++++
+
+It is up to the Board to define its own criteria and process of the Board's LFN
+Entry Review. The TAC recommends the Board make its LFN Entry Review criteria
+and process public and accept design input from the public.
+
+TAC Admission Review
+********************
+
+The TAC Admission Review is intended for the TAC to consider whether a
+Non-TAC Project should have a representative on the TAC. It is initiated by a
+TAC Admission Request from the Non-TAC Project.
+
+Required Information for TAC Admission Review
++++++++++++++++++++++++++++++++++++++++++++++
+
+An up-to-date instantiation of the Project Data Template is required for a TAC
+Admission Review.
+
+Criteria for TAC Admission Review
++++++++++++++++++++++++++++++++++
+
+Mandatory criteria for successful completion of the TAC Admission Review are
+maintenance of the mandatory criteria for LFN Entry and demonstration of
+adequate project Diversity, a clear statement of how the Project will select
+its TAC Representative and adherence to the LFN Principles.
+
+Outcome for TAC Admission Review
+++++++++++++++++++++++++++++++++
+
+Upon approval by the TAC of the Admission of a project to the TAC that project
+will be considered a TAC project. The TAC will notify the Board immediately of
+its decision.
+
+Archival Review
+***************
+
+A Project may be Archived if it has received no significant commits within the
+previous 12 months or by a majority vote of the Project's TSC to request the
+project be Archived. Prior to TAC initiation of an Archival Review of a
+Project, a good faith effort must be made to contact the Project's TSC and
+initiate a dialog about the future of the Project.
+
+Criteria for Archival Review
+++++++++++++++++++++++++++++
+
+Mandatory criteria for Archiving a project are one of:
+
+* A clear request from the Project to be archived.
+* Clear evidence of the project has received no significant commits within the
+ previous 12 months and demonstration of a good faith effort by the TAC to
+ contact the Project's TSC and come to a positive resolution.
+
+Outcome for Archival Review
++++++++++++++++++++++++++++
+
+The TAC will notify the Board immediately of any decision to Archive a project.
+
+LFN Exit Review
+***************
+
+A Project may request to leave the LFN by majority vote of its TSC.
+
+Should a project request to leave the LFN, it is the obligation of the TAC to
+forward that request to the Board immediately upon notification.
+
+The Board may cause a project to exit LFN at their discretion.
+
+Recommendations to Candidate Project
+------------------------------------
+
+The TAC will provide the following feedback to the candidate projects for all
+reviews.
+
+* If TAC recommends that the candidate project lifecycle state transition be
+ approved, the TAC will provide recommendations for improving the project.
+* If TAC recommends that the candidate project lifecycle state transition not
+ be approved, the TAC will give feedback about which criteria the project did
+ not adequately meet and what changes to the candidate project would be
+ required to change the TAC's recommendation.
+
+Disposition of Existing Projects
+--------------------------------
+
+OpenDaylight, OPNFV, FD.io, and ONAP are in state TAC. PNDA and SNAS are in
+state Non-TAC. Tungsten Fabric was `conditionally inducted by the Board
+<tf-condit-induct-email_>`__ as Non-TAC and should do an LFN Entry Review once
+the process is established.
+
+.. _tf-condit-induct-email: https://lists.lfnetworking.org/g/TAC/message/250
+
+Amendment of Technical Governance
+---------------------------------
+
+This Technical Governance may be amended by a 2/3 vote of the TAC subject to
+approval by the LFN Board.
--- /dev/null
+*********************
+Project Data Template
+*********************
+
+Instructions
+------------
+
+This document is a template to collect the data LFN thinks are relevant to LFN
+Project health. Projects will copy this template and instantiate it with their
+data as a part applying for lifecycle state transitions.
+
+ mkdir -p <relevant lifecycle transition dir>/<project name>/
+ cp project_data_template.rst !$/project_data.rst
+
+If the project has instantiated this template before they are welcome to start
+from that base and update it with any new information. Be sure that the data
+requested by the primary copy of the Project Data Template has not changed.
+
+These instructions should be removed from the instantiated template.
+
+Project Data
+------------
+
+Data that describes a Linux Foundation Networking Project. Provide links to
+authoritative public content or steps to reproduce results when possible.
+
+Project Vitals
+==============
+
+Basic information about the candidate project.
+
+* Project name
+* Project creation date
+* Project license
+* Project release schedule
+
+ * History of at least two years or age of project
+ * Planned future release schedule
+
+* Statement of alignment with LFN Charter/Mission
+
+Community Historical Trends
+===========================
+
+History of the candidate project's community.
+
+For each release or year for at least the last two years or the lifespan of the
+project, provide the following.
+
+* Contribution statistics
+
+ * Number of commits
+ * Number of non-trivial (generated code, version bump, ...) commits >5k LoC
+
+ * Merged by uploader
+ * Merged by committer from same organization as uploader
+ * Merged without substantial code review
+ * If the candidate project has sub-projects, group these by sub-project
+
+ * Number of commits per-organization
+
+* Contributor statistics
+
+ * Number of contributors
+ * Number of contributors per-organization
+
+Community Current Status
+========================
+
+Snapshot of the candidate project's community.
+
+* Committer statistics
+
+ * Number of committers
+ * Number of committers per-organization
+ * Number of active committers
+ * Number of active committers per-organization
+
+* Contributor approval process
+
+ * Contributor eligibility
+ * Process to become a contributor
+ * Process to remove a contributor
+
+* Committer approval process
+
+ * Committer eligibility
+ * Process to become a committer
+ * Process to remove a committer
+
+* Project governance structure
+
+ * Summery of project governance structure
+ * Summery of how project governance was established and can be modified
+ * Links to all public project governance documentation
+ * List of all community roles and details of how they are filled/emptied
+ * List of community roles that are elected
+ * List of community roles that are appointed
+ * List of people in all community roles and their organization affiliation
+
+* User community
+
+ * Summary of project user community
+
+Project Functionality
+=====================
+
+Details about the functionality of the candidate project.
+
+* Summary of candidate project functionality
+* Summary of candidate project technology components and purposes
+* Summary of where candidate project complements functionality already provided
+ by project(s) within LFN
+* Summary of where candidate project overlaps functionality already provided by
+ project(s) within LFN
+
+Project Tooling
+===============
+
+Details about the tooling used by the candidate project.
+
+* Bug tracker
+
+ * Links to bug trackers used by the candidate project.
+ * Integrated with any other relevant projects?
+ * To what extent are external/private bug trackers used?
+
+* Chat tooling
+
+ * Links to chat tooling used by the project.
+ * Overview of chat tooling used by the candidate project.
+ * To what extent is external/private chat tooling used?
+
+* Code repositories
+
+ * Links to code repositories used by the candidate project.
+ * Overview of code repositories used by the candidate project.
+ * To what extent are external/private code repositories used?
+
+* Code review
+
+ * Links to code review systems used by the candidate project.
+ * Overview of code review norms, practices, conventions, rules.
+ * To what extent are external/private code review systems used?
+
+* Continuous Integration tooling
+
+ * Links to CI jobs.
+ * Links to CI job definitions, infrastructure configuration.
+ * Overview of CI related to the candidate project.
+ * To what extent are external/private CI systems used?
+
+* Documentation
+
+ * Links to documentation for the candidate project.
+
+* Mailing lists
+
+ * Links to mailing lists used by the project and their archives.
+ * Overview of mailing lists used by the candidate project.
+ * To what extent are external/private mailing lists used?
+
+* Meeting calendars
+
+ * Link to docs about meetings related to the candidate project.
+ * Overview of meetings held by the candidate project.
+ * To what extent are meetings public, and clearly publicly documented?
+
+* Meeting minutes
+
+ * Link to archives for meeting minutes taken by the candidate project.
+ * To what extent are public minutes for meetings taken and shared?
+
+Integrations
+============
+
+Details about technical integrations implemented by the candidate project.
+
+* Summarize any existing or planned integrations with other projects.
+* Summarize any CI/CD integrations with other projects.
+* Summarize any other work that may enable integrations in the future.
+
+ * Continuous Delivery pipelines
+ * Configuration management tooling
+ * Documentation about cross-project integration
+ * APIs for cross-project integration
+
+Vocabulary Reference
+--------------------
+
+Explanations of domain-specific vocabulary.
+
+.. todo:: Look into using special rst to make these definitions into tooltips
+.. todo:: Consider extracting this to a stand-along file so can reuse elsewhere
+
+* Active
+
+ * In this context, typically related to the activity level of a project or
+ person.
+ * As a person: "Foo Committer on Bar Project has not sent any patches or done
+ any code review for Bar in the last 12 months. Bar's Project Lead reached
+ out to Foo Committer to discuss transitioning to an Emeritus Committer."
+ * As a project: "Bar Project has not had any non-trivial code changes merged
+ in the last 12 months. The LFN TAC reached out to Bar Project to discuss
+ transitioning to the LFN Archived lifecycle state."
+ * The LFN norm for "active" is about 12 months.
+
+* Committer
+
+ * Person with permission to cause commits to be merged into a project's
+ source control repositories.
+
+* Contributor
+
+ * Person who has contributed to a project. "Contributions" are broadly
+ defined. Examples include things like code, documentation, and bug tracker
+ changes.
+
+* Diverse
+
+ * In this context, typically related to the number of different organizations
+ involved in a project.
+
+* Downstream
+
+ * In this context, typically means the products based on a project.
+ Community collaborates on upstream project, which is downstreamed by a
+ company into a product.
+ * Alternatively, could relate to a relationship between two "upstream" open
+ source projects (not by-company products) where one consumes (is downstream
+ of) the other.
+ * As a verb: "to copy something from the open source project to a product
+ based on it".
+ * As a dependency relationship: "Linux is a downstream of C".
+
+* Upstream
+
+ * In this context, typically means the main open source project a community
+ collaborates on. The code, tooling and people that comprise a project.
+ * As a verb: "to add something to the main open source project".
+ * As a dependency relationship: "C is an upstream of Linux".
--- /dev/null
+*******************************************
+Linux Foundation Networking Fund Principles
+*******************************************
+
+LFN (Linux Foundation Networking Fund) is the shared home of previously
+independent communities with different backgrounds and histories. Each
+community has valuable lessons and practices to share with the others. The goal
+of this document is to find consensus on a common set of principles based on
+these experiences, to better forge a healthy community and meet the needs of
+all projects within LFN. This is a living document that future TACs should
+improve on.
+
+Autonomy of Projects
+====================
+
+Each LFN project is a self-governing community that is responsible for the
+project and creates its value. Each project knows best how to accomplish its
+mission, and can do so best by being supported but largely left to act
+autonomously.
+
+Each LFN project has a governing body such as a TSC. The role of LFN is to
+support projects' governing structures, not to burden them with excessive
+governance. When at all possible, decisions should be made by projects
+themselves, not the LFN.
+
+Because we give projects lots of responsibility, and support them from LFN's
+finite resources, we have high expectations for projects. When we consider
+accepting new LFN projects, we want to be sure that they have a healthy
+community and are on the right track for success.
+
+Contribute Upstream
+===================
+
+Organizations that get value from projects should give back to the upstream
+projects they get value from. Organizations that take without giving put the
+long-term sustainability of the project at risk.
+
+Ultimately, contributions take the form of human time. Organizations that get
+value from projects should contribute human time upstream, either directly via
+upstream contributions or indirectly by paying other organizations that
+contribute upstream.
+
+Cross-Project Integration
+=========================
+
+A major advantage of LFN is the cross-project collaboration it enables. From
+a technical standpoint, cross-project integration is a key element of enabling
+cross-project collaboration.
+
+Cross-project integration may take the form of Continuous Integration/
+Continuous Delivery pipelines connecting projects. These provide well-tested,
+recommended ways to deploy integrated projects, both in test and production
+environments. CI/CD pipelines can also enable quick feedback for developers
+about how changes in one project impact other projects, enabling quick, easy
+cross-project development.
+
+LFN should encourage projects to develop cross-project integrations.
+
+Diversity of Committers
+=======================
+
+The diversity of projects' committers is important for projects' health.
+Projects should strive to develop a set of committers from various
+organizations, not dominated by a single entity. Preventing a project from
+being dominated by a single interest gives confidence that contributions will
+be welcomed even if they do not align with the priorities of a dominant
+interest. This is a key element of ensuring stable long term growth of projects
+and attracting contributions.
+
+Diversity of Contributors
+=========================
+
+Thriving Open Source projects should have contributors from a diverse set of
+organizations. This prevents domination by a single entity, results in projects
+that can be more easily extended as they are not designed from a single
+viewpoint, encourages following an upstream-first development model and gives
+downstream users confidence that they can work with a project, not just a
+company.
+
+Listen to Users
+===============
+
+A project's user base is key to its success. LFN should encourage projects to
+proactively develop their user base and take user feedback, especially from
+users with real deployments, seriously.
+
+Users of LFN projects should contribute to LFN projects by giving feedback,
+sharing what they have learned, and clearly explaining their challenges.
+
+Marketplace of Ideas
+====================
+
+The goal of the Linux Foundation Networking Community is to promote development
+and adoption of the Open Source Networking ecosystem. The ecosystem will take
+the form of a marketplace of ideas, not a single reference implementation. It
+is not our job to select one solution or one single stack.
+
+This principle does not suggest that we should be entirely laissez faire. Doing
+so can be wasteful of community resources, counter productive and may result in
+multiple poor quality solutions. It does mean that we do not automatically
+reject projects because they are overlapping or competing when different design
+choices or market segments are being explored or addressed.
+
+Open Governance
+===============
+
+Open Source projects should be governed openly. Governance policies should be
+clearly defined and publicly, prominently available. Governance systems should
+be designed in the open, with input open to everyone.
+
+Although it is typically not possible to start an open source project using
+community-elected governance, as there is not a community to elect leaders
+from, projects should transition to a community-elected model as soon as
+possible.
+
+Open Source Tooling
+===================
+
+Open Source projects are only as Open Source as the tooling required to develop
+the project. Using non-Open Source tooling makes Open Source projects less
+Open Source. LFN should encourage projects to depend only on Open Source
+tooling whenever possible.
+
+In some cases, the productivity increase from using non-Open Source tooling may
+justify the loss of openness incurred. However, the choice to use non-Open
+tooling should not be made lightly, and the loss of openness incurred should be
+taken into account.
+
+In all cases and at all times choice of tooling belongs to the projects. At no
+time may choice of tooling be forced from outside the projects.
+
+Projects First and Only
+=======================
+
+Supporting the projects within LFN is LFN's primary concern. Supporting
+projects to achieve their goals is the best way to support Open Source
+Networking and the networking industry.
+
+Projects are the entities that get things done in LFN. Whenever possible, work
+should be done within projects, not LFN. LFN itself should remain a lightweight
+layer for collaboration among a set of projects. LFN may organize committees or
+working groups to facilitate collaboration.
+
+Public Tooling
+==============
+
+All tooling should be public and accessible to anyone. Additionally, the public
+tooling should be the primary tooling used for development.
+
+Examples of tooling that should be public:
+
+* Bug tracker
+* Chat tooling
+* Code repository
+* Code review
+* Continuous Integration tooling
+* Documentation
+* Mailing list
+* Meeting calendars
+* Meeting minutes
+
+Upstream-First
+==============
+
+Open Source projects typically work best when contributions are driven in the
+upstream project, using upstream discussion channels to build consensus and
+upstream code review tooling to iterate on proposals.
+
+The inverse, developing changes downstream and then "throwing them over the
+wall" to the upstream community, is typically fraught with problems. Diverse
+stakeholders in upstream communities typically bring viewpoints that result
+in changes that are more generically applicable, do not assume the specifics
+of the downstream's implementation. Maintaining downstream-only changes can
+result in costly rebases to consume new upstream changes, or falling behind
+upstream. Working upstream enables a culture of "collaborate on building
+together", which is materially better than "build things in silos and
+collaborate on combining them".
+
+On rare occasions it may be acceptable to develop code downstream and then
+push it upstream. For example, many new projects are seeded with ideas that
+started downstream.
+
+Specific upstream-first practices include:
+
+* Upstream code review is the primary forum for developing code, giving
+ feedback. Patches almost always require iterative feedback/fix cycles.
+ Large patches in particular often require input from many people over a long
+ period before they are ready to be merged. Large patches merged without
+ iterative feedback, especially by people from the same company, will raise
+ red flags.
+* Large features should be planned publicly, with community input.
Code Review / lfn / process.git / commitdiff