WORKFLOW.md

Specifications

A specification outlines our best understanding at the moment of how the software should be built. We want it to be as complete as possible so that when developers are reading a specification they can understand the complete context and future intentions of a component, even if the first developed version is an MVP.

• If a component is being built as a stand-in for a proper implementation, then the MVP should be written as a specification file.

While we are producing the detailed specifications for the Vega trading core, the RFC process (see Notes) would be too heavyweight, so we're starting off by directly editing specifications. When the core specifications are more stable, we will adopt the RFC process.

Pre-specification analysis

Some specification tasks will first require an analysis phase to investigate alternative ways of specifying the feature. Very early research and development of a feature will happen in the research repo and this will be reflected in a published paper in that repo. The analysis tickets in the product repo are to initiate and capture any discussion required before proceeding on to writing up the specification file. Analysis tasks should be created when required and all subject matter experts, relevant solution architects and engineers should be notified in the discussion.

Analysis tasks should be prioritised by those taking the lead on specifying the relevant feature. They may also be prioritised as a result of the engineering OKR goals, coordinated across the team.

The process for a new component

1. Create a ticket in the spec-writing board.
2. When you are ready to commence the spec writing task, move the ticket to a status of workflow::task-in-progress.
3. Create a merge request from the ticket - this will ensure they are linked and the ticket is automatically closed when merged.
4. Copy 0000-template.md to specs/0000-my-feature.md, (e.g. specs/0000-example-manager.md.
5. Fill in the details, including the acceptance criteria.
6. Submit a merge request to start soliciting feedback. Ensure that the appropriate team members are notified.
7. Build consensus and integrate feedback.
8. Assign a sequence number and make up a 4 letter code for your feature, (e.g. specs/0001-EXMP-example-manager.md)
9. Merge to master - this will automatically close the associated ticket.

The process for changes to existing component

1. Create an ticket in the spec-writing board. Label this appropriately, including whether it is a spec-bug or blocking-code and assign to a milestone and individual if appropriate. Only use the already created labels (see below for the defined list and raise a merge request against this file if you want to edit these).
2. This ticket will be prioritised by the person it is assigned to, in collaboration with the engineering team.
3. When you are ready to commence the spec writing task, move the ticket to a status of workflow::task-in-progress.
4. Create a merge request from this ticket with a brief description of the changes you need to make.
5. Using the automatically created branch, start editing the document. Make sure to edit acceptance criteria if appropriate.
6. Build consensus and integrate feedback.
7. Merge to master - this will automatically close the associated ticket.

The specification lifecycle

• When a specification is merged to a milestone branch, it is ready for development and if this requires any engineering implementation, a new implement ticket must be created in the implement board. The person responsible for creating this ticket is the person who has taken the lead on the specification task. See below for further information on implementation lifecycle.
• Scoping of specifications to milestones will be done in both spec-design and implement tickets rather than in the specification files.
• When a specification is merged into the master branch it details the specification of the protocol as its is deployed by the validators into mainnet.
• The master branch is always the default providing ease of access to the mainnet specifications. Special attention to branches should be taken when merging changes for milestone features that are yet to be deployed to mainnet.

Reviewing Specifications

When a pull request is open, this is a request for feedback from the author of the specification. It is the author's responsibility to solicit feedback from the appropriate development teams or system architects, but anyone is free to browse the open merge requests and pitch in.

Implementing a specification

When a specification is merged to master, it is ready for development. Not all specification updates will imply the need for an implementation task (for example, a spec bug). If an implementation task is required, a new implement ticket must be created in the implement board. The person responsible for creating this ticket is the person who has taken the lead on the specification task, in collaboration with the engineering team.

These issues will be prioritised on a weekly basis through a collaborative Slack meeting.

The relevant team can then break the specification down in to technical tasks in their own task system.

Issues should be created in the Product issue list to define a particular scope for an upcoming release/milestone. The specification should be as complete as it can be, while the issue may be a smaller piece on the way to implementing the first specification.

• Implementation tickets will be handled by the relevant team and linked back to the product tickets
• At the completion of implementation, the product ticket should be closed.
• Future work will be scoped in a new ticket
• Any changes to the specification should be done in new merge requests.

Notes

The workflow for this is partially based on the Rust RFC process, adapted for an earlier stage software design process.

It is being adopted as a replacement for using GitHub issues, which is where past product specifications have been written up.