Contributing

The UFO specification is a community project and problem reports and enhancement proposals are welcome. If you would like to propose a change or addition to the specification, please follow the process below.

Problem Identification

The process begins when a problem is identified. A problem may be a mistake in the current specification, a missing bit of data, a new idea that needs storage or something else. When defining the problem it is important to consider the following questions:

It’s also important to determine the scope of the problem:

If the problem is only affecting a single user, workflow or tool, it is often best to address the problem through an extension rather than a specification change. Extensions can be deployed faster and are more flexible than specification changes. If the problem does seem to need a specification change please open an issue. If you are unsure if you should open an issue, feel free to discuss the problem on the UFO Specification Google Group. Once the issue has been opened, a discussion will begin. (Please be patient as this project is managed by volunteers.) If the problem warrants a specification change, a solution development process will begin.

Solution Development

Solutions are developed collaboratively in the issue defining the problem. Ideally, the person who identifies the problem will lead, or at least participate in, the development of a solution to the problem. The development process is deliberately slow in order to keep the specification as clear of cruft as possible. Many ideas seem great at first, but over time better solutions evolve through collaboration or the ideas fall by the wayside altogether. Simple ideas with obvious solutions can move quickly, but more complex ideas need time to mature. There is no one development path for all solutions, but there are some general steps in the process.

Work out a solution in abstract.

It’s easy to get lost in the details of storage structures, but those are much easier to figure out once the problem at hand has been solved abstractly. It is usually best to first work out how to explain the solution to the problem rather than getting into the minute details. The following questions are the kinds of things to think about at this stage:

Determine how and where the data will be stored.

Once the general idea for a solution is worked out, the storage location and format need to be determined. The following guidelines apply to formats used within the UFO specification:

If a storage format for the data that fits these requirements already exists, the existing format should be considered instead of inventing a new format. Likewise, if there is data with a similar structure already in the UFO specification, the previously defined structure should serve as a model format.

Additions to the the specification can be stored in several places:

The location of the data must be coordinated with the format of the data. If the data will be added to an existing file, the format must adhere to the conventions of the existing file.

Determine the UFO versions that the solution applies to.

Once the storage location and format are determined, it’s possible to determine which versions of the specification will take the new change. These are the guidelines used to make this determination:

Changes that require a major format version increase.

A change that matches any of the following must wait for a full format version increase:

The only exceptions to this would be an extreme problem that requires an immediate change.

Changes that require a minor format version increase.

A change that matches any of the following must wait for a minor format version increase:

Changes that are backwards compatible.

Additions to, removal from and changes to the lib and data directory are backwards compatible, so they may be added at any point.

Document the change.

Once the format, location and specification versions are approved, the change should be documented in a fork of the specification. The documentation must be in the applicable places and follow the established formatting and language. A pull request may then be requested.

Evaluation Criteria

As a problem is discussed, the specification managers will advise the discussion as needed and evaluate the proposed solutions based on criteria such as:

Meetings

Historically there are informal meetings about the specification around the Robothon conference (held roughly every three years). On July 31, 2020, we had the first open virtual meeting, the notes of which are online.