DRAFT

Governance

TODO each page should describe flow updates to it occur

Project Charter

• To provide an Open-Source software development toolkit for use on modern hardware.
• To enable collaboration on the development of a platform that provides client virtualization technology with high assurance security properties that are rooted in the platform hardware.
• To engage with upstream software projects and contribute developments with the dual aims of increasing the use of OpenXT technologies and decreasing the specialization of OpenXT.
• To continually raise the security capabilities of the OpenXT platform and upstream projects.
• To satisfy the OpenXT Priority Use Cases.
• To actively pursue additional Use Cases where the OpenXT technology is relevant and the attraction of additional contributors would follow from adding support for a new Use Case.
  

This seems fine. Others might want to add to it.

Current Security Properties separate section, list and how to add.

TODO Platform Section, move use cases, security properties, layers here

Priority Use Cases

• Provide the software platform for a Multi-Tenant Client Desktop..

• Provide the software platform for a hardened Single-VM endpoint.

• Be the best-in-class Open Source toolchain for support of measured launch into a manageable virtualized environment.

• Provide a compelling platform for research and academic projects on hardware-based security technologies.

• Production software environment for validation of new hardware-based security technologies.
  

Repository Maintainer, Source Code Committer

• Position to be held while the appointment is supported by the Governance Board. 
• Monitors the repositories for Pull Requests and comments and engages with them.

• Apply the Pull Request Process and perform the actual approval or rejection actions of PRs to the source code repositories.

• Monitor mailing list postings that are relevant to RFCs and Pull Requests.

Current: Ross (AIS), Jed (AIS), Eric (AIS), Philip Tricca (unaffiliated)

Layers

OpenEmbedded supports composable software layers.

<< Proposed use of these layers by OpenXT needs to be described here – especially where layers can be used to resolve conflicting software priorities and requirements. >>

Project Governance Board

Structure of the Governance Board: 7 positions on the board.

An initial body of a seven individuals will be formed by community agreement. This body represents the interests of parties involved in the OpenXT project as well as the interests of the OpenXT platform itself.

Fragment, revise. The board is...

Responsible for ensuring that decision making is effective within the project and acting as the decision maker of highest authority, for setting the project charter and for driving project activities in pursuit of project goals derived from the charter.

This body will form a decision making authority to resolve issues that impact OpenXT and arrive at decisions on behalf of the whole community that cannot be easily resolved by the Pull Request process. Members of the Board are expected to provide guidance to project contributors on how to address challenges presented by proposed changes in order to seek solutions that are acceptable and desirable to all the project stakeholders and in alignment with the project charter.

The exact nature of the resolution may vary widely on a case by case basis.

• The board decides to request more information regarding a submission or RFC before further consideration.
• The board decides to request an alteration to a submission or RFC before further consideration or as criteria for acceptance.
• The board requests information from an outside expert or agency that can perform an evaluation, provide context and make recommendations to guide decision making.
• The board votes to accept/reject a proposed feature or change in OpenXT. This is a method of resolution of last resort: other approaches should be exhausted before a vote is required.

Decision Process

Action by the Governance Board will only be invoked in the situation where no resolution to a technical matter can be reached using the process of interaction with the repository maintainers and informal discussions. Action is initiated by creating a JIRA ticket to fully describe the technical issue that needs resolution. All activity concerning the resolution process will be tracked in the ticket. When a resolution of some form is reached, it will also be entered into the ticket. When the decided upon resolution is enacted, the ticket can be closed. This leaves a concrete information trail on exactly what transpired and what the resolution ultimately was.

If the decision process involves voting, this will be done with a simple +1 or -1 vote by each Board member. Any member can elect to abstain from voting for whatever reason public or private (which is a vote of 0). Voting can commence when any member of the Governance Board believes it is appropriate. The results of a vote will be recorded in the ticket.

In cases where members cannot participate because they are indisposed for whatever reason or when voting is tied, the Governance Board will have to make a best effort attempt at determining how to proceed.

I purposely made this vague since this is a grey area and will need to be handled on a case by case basis - it is probably sufficient to leave it as is.

Scope of Mandate

TODO Rich will fill in...

The scope of what the Board is mandated to make decisions on is limited to technical issues impacting OpenXT that cannot be resolved using the existing process. If the scope of this mandate needs to be expanded at a future date, this governance model will need to be altered with input and participation from the entire OpenXT community.

Changes to Board Structure

<< Process to be determined. >>

Workflow

Move pr process under here

Pull Request Process

• Monitor all new and existing PRs. Some PRs may be open but pending further evaluation because someone brought up a question or identified an issue that has not been addressed.
• Some PRs can get rejected right up front. These are ones that have obvious issues before any in depth review or testing is done.
  • The PR is a large feature change or addition and should have had an RFC done first.
  • The PR does not have a ticket. Aside from very minor PRs e.g. say one to un-break the build, all PRs should have a ticket.
  • Someone makes a specific request for something like documentation, diagrams or other supporting material before the PR is considered.
• Try to determine who might best be able to review and test the PRs. In a lot of cases this is reasonably obvious and one of the repository maintainers will just take it on, but there are challenging cases:
  
  • When the repository maintainers do not have the knowledge or familiarity with the language(s) the PR contains (e.g. JavaScript or Haskell). The maintainers will attempt to locate someone with those skills.
  • When the repository maintainers cannot reproduce the issue because of requirements for an appropriate environment or hardware. The maintainers will attempt to find someone who does.
  • When the repository maintainers know there are others who would be much better suited to evaluate a PR for a variety of reasons.
• Code review and static analysis of the PRs. The depth and nature of this is very specific to each PR and the language(s) it is written in. Maintainers take a best effort approach to this given the resources available.
• Determine what the best approach to test the PR is. This is very subjective and specific to each PR. The basic approaches are:
  • A full build on the build server with the PR specific changes in it is done then tested against instructions the author provides. This is done for large PRs (like new features) or PRs that not easily tested in isolation.
  • A partial build of the modules/components is done by one of us and tested in an existing build against instructions the author provides. This is done for smaller scope PRs where the changes are more isolated.
  • A full build on the build server with the PR specific changes where the success of the build is the only acceptance criterion. This is rare and is usually related to changes that only effect the build environment.
  • Testing is not done and we rely solely on inspection and review. This is exceedingly rare and only happens when the change is trivial or there are extenuating circumstances. The reasons for using this approach would be cited in the PR and/or the ticket.
• As a rule, people with commit access do not review, test and merge their own work. They must have someone else do this for them and, importantly, have some one else with commit access do the merge. The exception to the rule is really only cases where the build is broken and needs to be un-broken ASAP.
• A PR will hopefully reach the state where it can be merged. This could follow numerous paths as indicated above. When reviewers and testers have signed off, usually with an approval comment, the committer will then note that the PR is ready for merging by stating something like "will merge soon". This gives a final window for anyone to raise any issue or objection.
• Occasionally there will be PRs that have issues or concerns that the author has not addressed or commented on. In these cases we ping the author over a period of weeks/months and ask them to address the issues/concerns or close the PR out (and try again later hopefully). If after several attempts and a reasonably long period nothing happens, a dormant PR will be closed with an indication of the reason.

We should reword the following part to be a bit more formal. What is there is just sort of my informal ramblings. Escalate to board.

The above process has evolved as the current way that the maintainers operate.

Conflict resolution: The above process works in almost all cases. That does not mean PRs just get merged as fast as they come in. All community concerns and questions must be addressed before the PR can move along. In the end almost all issues or concerns can be addressed and we do move along, with the final recourse being escalation of the issue to the Project Governance Board.

One suggestion I have. I think it would be better to segregate the document into a governance section first and then a process section. The PR section above would go in the latter. In the latter would also go information about other assets on OpenXT (JIRA, Confluence, etc) and links to some of the other process pages like the RFC process and contributing.