From 7a71de75063c04dd8c732d9daa5df0d811aa0624 Mon Sep 17 00:00:00 2001 From: Jean-Francois Panisset Date: Sat, 21 Sep 2019 14:52:49 -0700 Subject: [PATCH] Document TSC process based on OpenVDB project Signed-off-by: Jean-Francois Panisset --- README.md | 70 +++++++++++++++++++++++++++++++++++--- tsc/charter.md | 62 +++++++++++++++++++++++++++++++++ tsc/meetings/yyyy-mm-dd.md | 28 +++++++++++++++ tsc/process/codereview.md | 26 ++++++++++++++ tsc/process/deprecation.md | 10 ++++++ tsc/process/release.md | 19 +++++++++++ tsc/process/security.md | 32 +++++++++++++++++ 7 files changed, 243 insertions(+), 4 deletions(-) create mode 100644 tsc/charter.md create mode 100644 tsc/meetings/yyyy-mm-dd.md create mode 100644 tsc/process/codereview.md create mode 100644 tsc/process/deprecation.md create mode 100644 tsc/process/release.md create mode 100644 tsc/process/security.md diff --git a/README.md b/README.md index 6869549..72ff4ef 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,81 @@ The purpose of this project is to provide a skeleton or sample Academy Software Foundation (ASWF) project reflecting the best practices that have been established by the Technical Advisory Committee (TAC). More detailed documentation can be found in the [Technical Advisory Committee repository](https://github.com/AcademySoftwareFoundation/tac). +## Project Submission and Graduation + +The process for submitting a project for ASWF membership is documented in the [Project Contribution Proposal Template](https://github.com/AcademySoftwareFoundation/tac/blob/master/process/proposal_template.md). Once a project has been accepted as an Incubation Stage project, the next step is to move the project towards the Adopted Stage, as documented in the [Project Lifecycle Document](https://github.com/AcademySoftwareFoundation/tac/blob/master/process/lifecycle.md). A major part of the Project Graduation requirements are covered by meeting the "passing" [criteria for the Best Practices badge](https://github.com/coreinfrastructure/best-practices-badge/blob/master/doc/criteria.md) defined by the [Linux Foundation's Core Infrastructure Initiative (CII)](https://bestpractices.coreinfrastructure.org/en). + +A lot of the information and files in this sample project are closely related to the CII badge requirements, or demonstrate the prefered way to implement these requirements in a ASWF project. + ## Source Code Repository -ASWF projects are hosted on GitHub under the [Academy Software Foundation organization](https://github.com/AcademySoftwareFoundation). +ASWF projects are hosted on [GitHub](https://github.com). Once a project has been been accepted as an Incubation Stage project, its repository will be moved under the [Academy Software Foundation organization](https://github.com/AcademySoftwareFoundation) which is managed by the Linux Foundation Release Engineering team. ## Licensing -ASWF projects must chose an explicit open source license, you can use the [Choose a License](https://choosealicense.com/) site to help pick one. Existing projects will typically want to stick to their existing license, as relicensing can be a complicated process. It is preferable to stick with an existing, unmodified, standard open source license since this simplifies the process of getting legal approval for use of the project within commmercial organizations, and allows the use of metadata to identify the project license. +ASWF projects should chose an explicit [Open Source Initiative](https://opensource.org/licenses) approved open source license, you can use the [Choose a License](https://choosealicense.com/) site to help pick one. Existing projects will typically want to stick to their existing license, as relicensing can be a complex process. It is preferable to select an existing, unmodified, standard open source license since this simplifies the process of getting legal approval for use of the project within commmercial organizations, and allows the use of metadata to identify the project license. If you are starting a new project, the ASWF recommends the use of the Apache License 2.0. -A copy of the license should be in the root directory of your repository and should be called LICENSE. If you are using a standard open source license you should also tag your GitHub project with that license. This can be done at project creation time. +A copy of the license should be in the root directory of your repository and should be called LICENSE. If you are using a standard open source license you should also tag your GitHub project with that license type. This can be done at project creation time. Source files in your project should use [Software Package Data eXchange (SPDX)](https://spdx.org/) identifiers to specify the project license, for instance in a C++ file: // SPDX-License-Identifier: Apache-2.0 - + +## Basic Documentation + +Your project should have a README.md file in the project home directory, identifying the project and providing enough information to orient new users towards information and resources relevant to the project. The prefered format for in-tree documentation files which are likely to be viewed via the GitHub web interface is [Markdown text](https://guides.github.com/features/mastering-markdown/). + +## Project Charter and Technical Steering Committee Documentation + +ASWF Projects are required to designate a Technical Steering Committee (TSC) which is responsible for the technical oversight of the project, and adopt a Project Charter, for which [a template is provided in the ASWF TAC repository](https://github.com/AcademySoftwareFoundation/tac/blob/master/process/charter_template.md). The TSC should meet regularly, and should keep public meeting minutes in the project repository. The TSC is responsible for setting the design, development, testing, release and support procedures for the project in close collaboration with the project community: close collaboration and alignment of processes between the TSCs of the various ASWF projects is encouraged but not mandatory. + +A suggested directory structure for the TSC-related documents based on the OpenVDB project is the following: + +``` +project +├── LICENSE +├── README.md +└── tsc + ├── charter.md + ├── meetings + │   └── yyyy-mm-dd.md + └── process + ├── codereview.md + ├── deprecation.md + ├── release.md + └── security.md +``` + +## Versioning and Releases + +## Security and Reporting Mechanism + +## Maintainers List + +## Website + +Consider hosting project web site from GitHub repository. + +## VFX Reference Platform + +## Build Tools + +CMake + +## Continuous Integration + +Azure Pipelines + +## Static Analysis + +SonarCloud, but lots of other options such as [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/), [Cppcheck[](http://cppcheck.sourceforge.net/), [Infer](https://fbinfer.com/), [LGTM](https://lgtm.com/). + +## Automated Test Suite + +## Ticketing System + +The ASWF provides an instance of the [JIRA ticketing system](https://jira.aswf.io/secure/Dashboard.jspa) for the use of its member projects. You will need to create a [Linux Foundation ID](https://identity.linuxfoundation.org/) to use this system. The native GitHub Issues mechanism in the project GitHub repository is also vailable. The TSC should define and document which ticketing system (or combination thereof) should be used and for what purpose. + +## Release Notes diff --git a/tsc/charter.md b/tsc/charter.md new file mode 100644 index 0000000..68e12ad --- /dev/null +++ b/tsc/charter.md @@ -0,0 +1,62 @@ +**Technical Charter (the "Charter") for [COMMUNITY NAME]** **a Series of LF Projects, LLC** + +**Adopted \_\_\_\_\_\_\_\_\_\_\_** + +This charter (the "Charter") sets forth the responsibilities and procedures for technical contribution to, and oversight of, the **[COMMUNITY NAME]** project, which has been established as **[COMMUNITY NAME]** a Series of LF Projects, LLC (the "Project"). LF Projects, LLC ("LF Projects") is a Delaware series limited liability company. All Contributors to the Project must comply with the terms of this Charter. + +1. Mission and Scope of the Project + * **a.** The mission of the Project is to develop an open source project with the goals indicated in the "README" file within the Project's code repository. + * **b.** The scope of the Project includes software development under an OSI-approved open source license supporting the mission, including documentation, testing, integration and the creation of other artifacts that aid the development, deployment, operation or adoption of the open source software project. +2. Technical Steering Committee + * **a.** The Technical Steering Committee (the "TSC") will be responsible for all technical oversight of the open source Project. + * **b.** The TSC voting members are initially the Project's Committers. At the inception of the project, the Committers of the Project will be as set forth within the "CONTRIBUTING" file within the Project's code repository. The TSC may choose an alternative approach for determining the voting members of the TSC, and any such alternative approach will be documented in the CONTRIBUTING file. Any meetings of the Technical Steering Committee are intended to be open to the public, and can be conducted electronically, via teleconference, or in person. + * **c.** TSC projects generally will involve Contributors and Committers. The TSC may adopt or modify roles so long as the roles are documented in the CONTRIBUTING file. Unless otherwise documented: + * **i.** Contributors include anyone in the technical community that contributes code, documentation, or other technical artifacts to the Project; + * **ii.** Committers are Contributors who have earned the ability to modify ("commit") source code, documentation or other technical artifacts in a project's repository; and + * **iii.** A Contributor may become a Committer by a majority approval of the existing Committers. A Committer may be removed by a majority approval of the other existing Committers. + * **d.** Participation in the Project through becoming a Contributor and Committer is open to anyone so long as they abide by the terms of this Charter. + * **e.** The TSC may (1) establish work flow procedures for the submission, approval, and closure/archiving of projects, (2) set requirements for the promotion of Contributors to Committer status, as applicable, and (3) amend, adjust, refine and/or eliminate the roles of Contributors, and Committers, and create new roles, and publicly document any TSC roles, as it sees fit. + * **f.** The TSC may elect a TSC Chair, who will preside over meetings of the TSC and will serve until their resignation or replacement by the TSC. ** ** The TSC Chair, or any other TSC member so designated by the TSC, will serve as the primary communication contact between the Project and the Technical Advisory Council of the Academy Software Foundation of The Linux Foundation. + * **g.** Responsibilities: The TSC will be responsible for all aspects of oversight relating to the Project, which may include: + * **i.** coordinating the technical direction of the Project; + * **ii.** approving project or system proposals (including, but not limited to, incubation, deprecation, and changes to a sub-project's scope); + * **iii.** organizing sub-projects and removing projects; + * **ii.** creating sub-committees or working groups to focus on cross-project technical issues and requirements; + * **v.** appointing representatives to work with other open source or open standards communities; + * **vi.** establishing community norms, workflows, issuing releases, and security issue reporting policies; + * **vii.** approving and implementing policies and processes for contributing (to be published in the CONTRIBUTING file) and coordinating with the Series Manager to resolve matters or concerns that may arise as set forth in Section 7 of this Charter; + * **viii.** discussions, seeking consensus, and where necessary, voting on technical matters relating to the code base that affect multiple projects; and + * **ix.** coordinating any marketing, events, or communications regarding the Project with the LF Projects Manager or their designee. +3. TSC Voting + * **a.** While the Project aims to operate as a consensus based community, if any TSC decision requires a vote to move the Project forward, the voting members of the TSC will vote on a one vote per voting member basis. + * **b.** Quorum for TSC meetings requires at least two-thirds of all voting members of the TSC to be present. The TSC may continue to meet if quorum is not met, but will be prevented from making any decisions at the meeting. + * **c.** Except as provided in Section 7.c. and 8.a, decisions by vote at a meeting require a majority vote of those in attendance, provided quorum is met. Decisions made by electronic vote without a meeting require a majority vote of all voting members of the TSC. + * **d.** In the event a vote cannot be resolved by the TSC, any voting member of the TSC may refer the matter to the Series Manager for assistance in reaching a resolution. +4. Compliance with Policies + * **a.** This Charter is subject to the Series Agreement for the Project and the Operating Agreement of LF Projects. Contributors will comply with the policies of LF Projects as may be adopted and amended by LF Projects, including, without limitation the policies listed at https://lfprojects.org/policies/. + * **b.** The TSC may adopt a code of conduct ("CoC") for the Project, which is subject to approval by the Series Manager. Contributors to the Project will comply with the CoC or, in the event that a Project-specific CoC has not been approved, the LF Projects Code of Conduct listed at https://lfprojects.org/policies/. + * **c.** When amending or adopting any policy applicable to the Project, LF Projects will publish such policy, as to be amended or adopted, on its web site at least 30 days prior to such policy taking effect; provided, however, that in the case of any amendment of the Trademark Policy or Terms of Use of LF Projects, any such amendment is effective upon publication on LF Project's web site. + * **d.** All participants must allow open participation from any individual or organization meeting the requirements for contributing under this Charter and any policies adopted for all participants by the TSC, regardless of competitive interests. Put another way, the Project community must not seek to exclude any participant based on any criteria, requirement, or reason other than those that are reasonable and applied on a non-discriminatory basis to all participants in the Project community. + * **e.** The Project will operate in a transparent, open, collaborative, and ethical manner at all times. The output of all Project discussions, proposals, timelines, decisions, and status should be made open and easily visible to all. Any potential violations of this requirement should be reported immediately to the LF Projects Manager. +5. Community Assets + * **a.** LF Projects shall hold title to all trade or service marks used by the Project ("Project Trademarks"), whether based on common law or registered rights. Project Trademarks shall be transferred and assigned to LF Projects to hold on behalf of the Project. Any use of any Project Trademarks by participants in the Project shall be in accordance with the license from LF Projects and inure to the benefit of LF Projects. + * **b.** The Project shall, as permitted and in accordance with such license from LF Projects, develop and own all Project GitHub and social media accounts, and domain name registrations created by the Project community. + * **c.** Under no circumstances shall LF Projects be expected or required to undertake any action on behalf of the Project that is inconsistent with the tax-exempt status or purpose, as applicable, of LFP, Inc. or LF Projects, LLC. +6. General Rules and Operations. + * **a.** The Project will: + * **i.** engage in the work of the project in a professional manner consistent with maintaining a cohesive community, while also maintaining the goodwill and esteem of LF Projects, LFP, Inc. and other partner organizations in the open source software community; and + * **ii.** respect the rights of all trademark owners, including any branding and trademark usage guidelines. +7. Intellectual Property Policy + * **a.** Participants acknowledge that the copyright in all new contributions shall be retained by the copyright holder as independent works of authorship and that no contributor or copyright holder will be required to assign copyrights to the Project. + * **b.** Except as described in Section 7.c., all code contributions to the Project are subject to the following: + * **i.** All new inbound code contributions to the Project must be made using the **[Apache License, Version 2.0 (available here: [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0))]** (the "Project License"). + * **ii.** All new inbound code contributions must: + 1. **[//For projects using a CLA (or ICLA+CCLA)// be made pursuant to a duly executed Project Contribution License Agreement (the "CLA"), available on the Project's web site; and]** + 2. be accompanied by a Developer Certificate of Origin ([http://developercertificate.org](http://developercertificate.org)) sign-off in the source code system that is submitted through a TSC-approved contribution process which will bind the authorized contributor and, if not self-employed, their employer to the applicable license; + * **iii.** All outbound code will be made available under the Project License. + * **iv.** Documentation will be received and made available by the Project under the Creative Commons Attribution 4.0 International License (available at [http://creativecommons.org/licenses/by/4.0/](http://creativecommons.org/licenses/by/4.0/)). + * **V.** The Project may seek to integrate and contribute back to other open source projects ("Upstream Projects"). In such cases, the Project will conform to all license requirements of the Upstream Projects, including dependencies, leveraged by the Project. Upstream Project code contributions not stored within the Project's main code repository shall comply with the contribution process and license terms for the applicable Upstream Project. + * **c.** If an alternative inbound or outbound license is required for compliance with the license for a leveraged open source project or is otherwise required to achieve the Project's mission, the Governing Board of the Academy Software Foundation of The Linux Foundation ("Governing Board") or the Governing Board's designated committee may approve the use of an alternative license for specific inbound or outbound contributions on an exception basis. Any exceptions must be approved by a vote of the Governing Board and must be limited in scope to what is required for such purpose. To request an exception, please describe the contribution, the alternative open source license(s), and the justification for using an alternative open source license for the Project. + * **d.** Contributed files should contain license information, such as SPDX short form identifiers, indicating the open source license or licenses pertaining to the file. +8. Amendments + * **a.** This charter may be amended by a two-thirds vote of the entire TSC and is subject to approval by LF Projects. diff --git a/tsc/meetings/yyyy-mm-dd.md b/tsc/meetings/yyyy-mm-dd.md new file mode 100644 index 0000000..c419391 --- /dev/null +++ b/tsc/meetings/yyyy-mm-dd.md @@ -0,0 +1,28 @@ +# AWSF Project TSC Meeting - Month DD, Year + +## Voting member attendance + +* [ ] Person A - Chairperson, Affiliation A +* [ ] Person B, Affiliation B +* [ ] Person C, Affiliation C +* [ ] Person D, Affiliation D + +# Agenda + +- First Item + +- Second Item + - First Sub Item + - Second Sub Item + - Third Sub Item + +- Third Item + +- Next meeting + +# Action Items (AIs) + +# Notes + +# Chat + diff --git a/tsc/process/codereview.md b/tsc/process/codereview.md new file mode 100644 index 0000000..41ea477 --- /dev/null +++ b/tsc/process/codereview.md @@ -0,0 +1,26 @@ +# Code Reviewing and Merging PROJECT Pull Requests + +This documents the code review and merging process adopted by the OpenVDB TSC, and can be used as a basis for other ASWF projects. + +The Technical Steering Committee have write-access to the PROJECT repository and are responsible for triaging, reviewing and ultimately merging or rejecting GitHub pull requests. This document lists the policy and best practices to guide the TSC in this process. + +## Policy + +* No direct commits to the master (or any other protected) branch, every code change should be a pull request +* Any member of the community can provide feedback on any pull request (and is encouraged to do so) +* A CODEOWNERS file introduced to the root of the repo to configure ownership (global, per-directory and/or per-file) - this will automatically request pull request reviews from the relevant maintainers (https://help.github.com/articles/about-codeowners/) +* Minimum of one non-author TSC member approval on every pull request before merging +* Non fast-forward merges must be used (ie the merge must not be rebased onto master) +* Azure Pipelines CI and DCO status checks must strictly pass before merging, other (TBD) checks should loosely pass (https://help.github.com/articles/types-of-required-status-checks) + +## Best Practices + +* Prefer all requested reviewers to approve before merging +* Merging a pull request should be the responsibility of the author if they are a TSC member +* Any TSC member can merge a pull request authored by a non-TSC member, but with a preferred minimum of two approvals from TSC members (including themself) +* Re-writing the branch history by rebasing a pull request branch just before a merge is discouraged, unless it significantly improves the overall history (such as any broken commits on the review branch that might make reverting or bisecting more difficult) +* Prefer pull requests to be open for a minimum of 72 hours before merging in order to gather any feedback +* Aim for all pull requests to be responded to by one of the TSC members within a minimum of two weeks with either explanation of non-acceptance, request for changes or merge +* TSC meetings should regularly review and discuss any outstanding pull requests +* Pull requests should link to the associated ticketing system ticket (if applicable) in the description or title, this provides a route back to the ticketing system ticket through the Git history (git blame -> PR merge -> ticketing system ticket) +* All pull request comments should aim to be answered and resolved before committing diff --git a/tsc/process/deprecation.md b/tsc/process/deprecation.md new file mode 100644 index 0000000..4eccaaa --- /dev/null +++ b/tsc/process/deprecation.md @@ -0,0 +1,10 @@ +# Deprecation Strategy for PROJECT + +This should discuss the following topics: + +- How many major versions of PROJECT are supported +- How this interacts with versions of the [VFX Reference Platform](http://www.vfxplatform.com/) +- How this interacts with versions of commercial DCC applications that use PROJECT +- How far back does API or ABI compatibility extend += There should be an explicit policy on fixing severe security issues in versions that are no longer supported. +- Any other relevant information useful to PROJECT users when making decision about the lifecycle of the project. diff --git a/tsc/process/release.md b/tsc/process/release.md new file mode 100644 index 0000000..4b321d8 --- /dev/null +++ b/tsc/process/release.md @@ -0,0 +1,19 @@ +# Release Process for PROJECT + +This release process is the one adopted by the [OpenVDB project](https://github.com/AcademySoftwareFoundation/openvdb), it is provided as an example of a well structured release process. + +The following assumes that the current PROJECT library version number is 6.0.0 and the new version number is 6.1.0. Adjust for the actual version numbers as appropriate. + +- [ ] Open a ticketing system ticket "Release PROJECT 6.1.0" ticket with "PROJECT_6.1.0" as the Fix Version. +- [ ] Update `CHANGES` with release notes. (A project may want to adopt automated tools for release notes management / generation). +- [ ] Open a pull request to merge the above changes into `PROJECT/master`. Associate the pull request with the ticketing system ticket created earlier, and verify that the CI build runs successfully. +- [ ] Draft a new GitHub release. Title it "PROJECT 6.1.0" and tag it as `v6.1.0`. +- [ ] Update front page of project web site with a news item announcing the release, and delete the oldest news item. Open that page in a browser and check that the website renders correctly and that there are no broken links. +- [ ] Build the auto-generated documentation with the appropriate build system targets and replace the contents of the project website documentation directory with the output. +- [ ] Open a pull request to merge the above changes into the website repository. Associate the pull request with the ticketing system ticket created earlier. +- [ ] Post a release announcement to the PROJECT public announcement mailing list. +- [ ] In preparation for the next release, change the correct #define in the project's base version include file. Unless it is known that the next release will include API- or ABI-breaking changes, increment only the patch number to begin with (in this case, from 6.1.0 to 6.1.1). Update any references to the project version number in the documentation source files, and add a "Version 6.1.1 - In development" section to the `CHANGES` release notes file. Open a pull request to merge these changes into `PROJECT/master`. +- [ ] Add a "PROJECT_6.1.1" version to the ticketing system. + +END + diff --git a/tsc/process/security.md b/tsc/process/security.md new file mode 100644 index 0000000..d76f716 --- /dev/null +++ b/tsc/process/security.md @@ -0,0 +1,32 @@ +# Security and PROJECT + +General discussion of PROJECT security posture. + +## Reporting + +Document process for external parties to report security issues. A private mailing list reaching only the TSC members should be provided to allow confidential reporting when needed, such as to avoid public disclosure before a vulnerability can be addressed in a release. + +## Vulnerabilty Handling + +Document the process and timeframe that the project is committed to following to address security issues. There should be an explicit policy on fixing severe security issues in versions that are no longer supported. + +## Outstanding Security Issues + +A list of current, unaddressed security issues, with an assessment of severity and a timeframe for resolution. Publicly disclosed [CVEs](https://cve.mitre.org/) should be listed here. + +## Addressed Security Issues + +A historical list of addressed security vulnerabilities, in particular any public CVEs, with corresponding release information. + +## File Format Expectations + +Assuming PROJECT defines a data file format, a discussion of what a user should expect happens when operating on a valid or invalid PROJECT data file. + +## Runtime Library Expectations + +Assuming PROJECT defines a callable API / library, a discussion of how the library is expected to behave, how it handles erroneous inputs / does input sanitization, how it returns errors. + +## Data and Metadata Implications + +A discussion of issues relating to the data model implemented by the project such as correctness, confidentiality, potential misuse... +