Skip to content

Latest commit

 

History

History
78 lines (49 loc) · 7.28 KB

CONTRIBUTING.md

File metadata and controls

78 lines (49 loc) · 7.28 KB
Raw

Ably Features Specification: Contributing Guidelines

Local Development Workflow

Please use our GitHub workflows (Check and Assemble) as the canonical source of truth for how this codebase is validated and built in CI, however to get you up and running quickly the local development experience goes like this:

Required Development Tools

You'll need Ruby and Node.js installed. Consult our .tool-versions file for the versions that we use to validate and build in CI. This file is of particular use to those using asdf or compatible tooling.

Installing Dependencies

When you've just cloned the repository or you've switched branch, ensure that you've installed dependencies with:

npm install

The scripts folder contains code written in Ruby, however those scripts are intentionally self-contained, so there is no need to discretely install Ruby dependencies outside of what is done inline in those script files.

Build and Preview

To build the static HTML microsite that's generated from the source files in this repository:

npm run build

Then to open that in your browser to preview:

open output/index.html

On macOS systems that will open it using the file:// URL loading scheme. This means that navigating to the folders for each page will require two clicks, first into the folder and then onto the index.html document within that folder.

If you make a change to a source file then you will need to npm run build again and then refresh your browser.

We plan to improve this developer experience when we work on #90, by adding a local development HTTP server.

Features Spec Points

When making changes to the spec, please follow these guidelines:

  • Ordering: Spec items should generally appear in ID order, but priority should be placed on ordering them in a way that makes coherent sense, even if that results in them being numbered out-of-order. For example, if XXX1, XXX2 and XXX3 exist but it would make more sense for XXX3 to follow XXX1, then just move the spec items accordingly without changing their IDs
  • Structuring: When structuring the specification and defining the relationships between clauses and subclauses, generally avoid placing behavior descriptions and implementation details in the parent clause. The parent clause should primarily serve as an informational header for its subclauses. However, if it improves coherence, including behavior descriptions in the parent clause is permissible.
  • Clarity: Refrain from using conditional statements and multiple behavior descriptions within a single spec item. These should be separated into distinct subclauses for clarity.
  • Addition: When adding a new spec item, choose an ID that is greater than all others that exist in the given section, even if there is a gap in the currently assigned IDs.
  • Modification: Spec items should never be mutated, except to patch a mistake that doesn't change the semantics for SDK implementations. Follow the guidance outlined here in respect of Replacement if the meaning or scope of a spec point needs to change.
  • Removal: When removing a spec item, it must remain but replace all text with This clause has been deleted. It was valid up to and including specification version @X.Y@. (uses textile markup).
  • Replacement: When replacing a spec item, it must remain but replace all text with This clause has been replaced by "@Z@":#Z. It was valid up to and including specification version @X.Y@. (uses textile markup).
  • Deprecation: Our approach to deprecating features is yet to be fully evolved and documented, however we have a current standard in place whereby the text "(deprecated)" is inserted at the beginning of a specification point to declare that it will be removed in a future release. The likely outcome is that in the next major release of the spec/protocol we'll remove that spec item, per guidance above.

Additional Notes on Features Spec Point Removal and Replacement

Specification version references included in Removal and Replacement notices are in the form X.Y because they only need to include the major (X) and minor (Y) components of the specification version. See Specification Version.

If the clause being removed or replaced has subclauses then the expected implication is that they are also being removed or replaced. Therefore, aligned with this guidance, they must remain but with their text replaced. This might mean that in some cases, for example, a clause is marked as replaced but some or all of its subclauses are marked as removed.

Variations on the replacement text for removed or replaced spec items is allowed, as long as the overarching structure remains the same. For example:

  • When a spec item has been removed because a new spec point has made it redudant, which is the case for RTN15f after specification version 1.2, where the replacement text is: This clause has been deleted (redundant to "RTN19a":#RTN19a). It was valid up to and including specification version @1.2@.
  • When a spec item has been replaced by more than one new spec item, which is the case for RTN16b after specification version 1.2, where the replacement text is: This clause has been replaced by "@RTN16g@":#RTN16g and "@RTN16m@":#RTN16m. It was valid up to and including specification version @1.2@.

Historically, before the above guidance was established - in particular around Removal and Replacement - there have been some cases where spec points were completely deleted. This left us open to the problem that client library references to spec items could end up semantically invalid if that spec point was re-used later. For example, if XXX1a and XXX1c exist but XXX1b doesn’t because it was removed in the past (prior to this guidance being established), then we should introduce XXX1d for the new spec item rather than re-using XXX1b.

Release Process

Use our standard Release Process, where:

  • there is no 'Publish Workflow' to be triggered in this repository
  • the version to be bumped in the release branch is the Specification Version
  • in addition to pushing a full Git version tag (to persist as static and immutable) in the form v<major>.<minor>.<patch>, tags should also be added or moved for higher levels of specification version granularity:
    • v<major>.<minor> - e.g. v1.2 for latest patch to version 1.2 of the specification
    • v<major> - e.g. v2 for the latest enhancements and patches to version 2 of the specification

It's worth emphasising here, for clarity, that bumps to the Protocol Version or Build Version are not part of the release process and do not appear in release branches or the pull requests that represent those release branches. If these versions need to be bumped then that is done as part of a feature change or addition, where that feature is then subsequently implicitly incorporated into a release at the time of executing the release process.