Process 2015

This is an attempt to capture the current process that is in place for working on the OpenXT project and within the community. While we do not as of yet have what would more properly be called a governance model, we do in fact have processes in place for the project. Some portions of the process are explicitly documented and agreed upon and some have evolved over the past year and some months.

Contributing

Guidelines for contributing have been in place for some time now. Refer to:

How to contribute

Coding pages

The RFC process has worked reasonably well to allow comments and discussion on bigger changes to OpenXT. There have been some disagreements over what exactly an RFC should be but from the beginning we wanted to keep the definition loose to encourage any sort of submission. If community members feel an RFC is incomplete they are free to express that opinion (and in cases they have). The coding standards have been mostly uncontroversial and the pull request (PRs for short) process has seemed to work well though it requires diligence to prevent PRs from languishing without attention. Using the JIRA ticket system has also worked out well for the project. On the whole, these areas of the process have been reasonably successful.

Maintainers and Roles 

At present we do not have well defined roles on the OpenXT project. What we do have is a function of realities on the ground and how the process, as it related to this area, has evolved. There are numerous OpenXT assets and different people help maintain them and perform work on them. Most of them like JIRA ticket system, the Confluence Wikis, the Google Groups mailing list have not required a lot of maintenance. We have mostly adopted an open door policy to these assets allowing people to join them/access them if they wish.

The more interesting aspect to this is how the process has evolved with respect to accepting actual changes into the OpenXT code base. There were early attempts to define roles and groups for maintaining certain areas of the code base. This partially worked; there are some groups that are based around functional areas of the project. These groups have small numbers of members who can commit changes to certain repositories and those members were voted into those groups. Most of the work of eventually accepting changes into the code base though has fallen to a small group of owners/admins who were there from the creation of the OpenXT project and are tasked with working on OpenXT (specifically I am referring to Eric, Jed and Ross). The end result is that we three form the members of the loosely defined "maintainers" role/group with others involved from time to time. Note that the one thing that is exclusive to this group/role is "eventually accepting changes"; we always want to encourage as much analysis, code reviewing, testing, etc of all PRs by as many people as are willing.

PR Process

A process has also evolved for handling PRs. This is not something that was written down (prior to this) or explicitly decided on. It is just basically how we have come to do this. These are some of the aspects of that 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 three of us will just take it on or ask another to. There are cases where this won't work though.
  • When none of us has the knowledge or familiarity with the language(s) the PR contains (e.g. JavaScript or Haskell). In these cases we attempt to locate someone with those skills.
  • When we cannot reproduce the issue because we do not have the appropriate environment or hardware. In these cases we attempt to find someone who does.
  • When we 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. We 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 a +1 and a 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, we will close a dormant PR and cite the reason.

As was stated, this process has evolved as the way we do things. The aspects of handling PRs listed above is not exhaustive. There are other special cases that arise and we do our best to deal with them. We try to always execute this process with best of intentions. In the worst case where mistakes are made or something comes to light after the fact, we always have remediation through the code control system.

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. There are cases (and anyone who has been present in the community will know of one or two) where we cannot come to a resolution. Some believe this is because we lack a basic governance structure to come to a resolution. Right now the de facto resolution in all these cases is to do nothing which causes frustration in the community.

On to 2016

Towards the end of 2015 discussions began on adopting some governance model of yet unknown scope. We will see where this goes...