...
This portion of the governance documentation deals with day to day processes and workflows on the OpenXT project. The processes listed here are less formal and have evolved as work has progressed on the project. These processes are also subject to change if it is needed or if the community desires it.
Contributing
Guidelines for contributing have been in place for some time now. Please refer to:
Source Code
All source code (and certain other material like documents and the BVT test harness) resides in public git repositories on GitHub. There are currently two organizations:
...
The first is the primary organization where all the currently active projects reside. The latter is primarily for two purposes. The first is to collect related projects that are not central to OpenXT (like build machine setup scripts e.g.). Secondly it is used as a place to move repositories when they become obsolete. The allows the project to leverage GitHub's redirects functionality. See the section "Redirects and Git Remotes" on the Transferring a repository page (as well as the Renaming a repository page).
GitHub Pull Requests
The primary method for contributing on the OpenXT project is using the GitHub Pull Request process. See the GitHub documentation on Pull Requests for a full description on how it works:
OpenXT Pull Request Process
The following process has evolved as the standard way in which the vast majority of Pull Request (PR) submissions are handled.
- 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.
- Finally there is the (rare) case where the PR cannot be considered further. In general, all community concerns and questions must be addressed before the PR can proceed to a merge-able state. If there is conflict in the community over the PR the final recourse is escalation of the issue to the Project Governance Board.
GitHub Teams and Roles
To date the definition of GitHub teams and project roles has been ill defined. There are a number of teams centered around functional areas in OpenXT (see https://github.com/orgs/OpenXT/teams). The process for adding a member to a team is basically to nominate the person on the mailing list and vote with +/-1. The Owners and Admin teams have remained static since the formation of the OpenXT project. The process of defining and managing teams and roles needs to be more well defined going forward. It will also need to accommodate different roles and procedures on different layers in OpenXT.
Other OpenXT Assets
The following are the various other assets and services that make up the OpenXT project. There is a brief description on the process of managing these assets as it is currently done. If any conflict or issue arose with an existing process detailed below, it would result in an escalation to the Project Governance Board.
Google Groups mailing list
The OpenXT project currently has a open policy for joining the mailing list. Anyone who has asked to join has been added.
https://groups.google.com/forum/#!forum/openxt
JIRA ticket system
The JIRA ticket system is read-only accessible to the general public. The OpenXT project currently has a open policy for new users in the JIRA ticket system. Mostly if someone requests access it is granted, provided some members of the community know the person.
https://openxt.atlassian.net/secure/Dashboard.jspa
Confluence wikis
The public Confluence wikis are read-only accessible to the general public. Private user pages are under the control of individual users. There is no set guideline for getting modify access to the public Confluence wikis. It would most likely be a post the the mailing list asking for access and if there are no objections, the person could be added.
https://openxt.atlassian.net/wiki/
OpenXT Website
The main OpenXT website resides in a GitHub repository and is modified or contributed to under the Source Code processes outline above.
Changes to this Governance Document
Changes to the processes and workflows described in this document (and related process documents that are linked from this) are generally decided by community discussion. Some of the processes have just evolved with no objections from the community. If any conflict or issue arose with this mode of changing these processes or workflows it would result in an escalation to the Project Governance Board.
License of this Governance Document
| Info | ||
|---|---|---|
| ||
Copyright 2016 by individual contributors. This work is licensed under the Creative Commons Attribution |
Revision History of this Governance Document