From 3b65c1418e927b574431c471b30ad4aa62665ba0 Mon Sep 17 00:00:00 2001 From: Quintin Willison Date: Mon, 3 Oct 2022 14:42:48 +0100 Subject: [PATCH 1/3] Add contributing guidance. --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++++ 2 files changed, 56 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..34af7fe3b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# 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](.tool-versions) for the versions that we use to validate and build in CI. +This file is of particular use to those using [asdf](https://asdf-vm.com/) 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](scripts/) 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](https://github.com/ably/specification/issues/90), +by adding a local development HTTP server. + +## Features Spec Points + +When making changes to [the spec](textile/features.textile), 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 +- **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. This is desirable so that client library references to spec items are still semantically valid even after they are removed from the spec rather than now having different semantics due to the ID being re-used. For example, if `XXX1a` and `XXX1c` exist but `XXX1b` doesn’t because it was removed in the past, then introduce `XXX1d` for the new spec item rather than re-using `XXX1b` +- **Removal**: When removing a spec item, it must remain but replace all text with “This clause has been deleted.”. See [#1057](https://github.com/ably/docs/pull/1057) for an example of this in practice. +- **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. + +## Release Process + +This will be documented when we work on +[#6](https://github.com/ably/specification/issues/6). diff --git a/README.md b/README.md index d832d08cb..90404df15 100644 --- a/README.md +++ b/README.md @@ -7,3 +7,7 @@ _[Ably](https://ably.com) is the platform that powers synchronized digital exper ## Overview This repository has been created as the new home for the 'features spec' that describes the interfaces, implementation details and behaviours of SDKs (sometimes referred to as client libraries) that provide application developers with support to integrate and leverage the Ably platform in their solutions. + +## Contributing + +For guidance on how to contribute to this project, see [CONTRIBUTING.md](CONTRIBUTING.md). From e141baa088ffc2be5af168b82e47aa1b5f4bae35 Mon Sep 17 00:00:00 2001 From: Quintin Willison Date: Mon, 3 Oct 2022 19:18:40 +0100 Subject: [PATCH 2/3] Make references to CI workflows hyperlinks in the contributing guidance. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34af7fe3b..bc9bce02c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## 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: +Please use our GitHub workflows ([Check](.github/workflows/check.yaml) and [Assemble]((.github/workflows/assemble.yaml))) 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 From 258f86c6577f57ac882d5d53e588c479dae34d4c Mon Sep 17 00:00:00 2001 From: Quintin Willison Date: Mon, 3 Oct 2022 19:19:42 +0100 Subject: [PATCH 3/3] Make first mentions of Ruby and Node.js hyperlinks in the contributing guidance. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc9bce02c..01f859d13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Please use our GitHub workflows ([Check](.github/workflows/check.yaml) and [Asse ### Required Development Tools -You'll need Ruby and Node.js installed. +You'll need [Ruby](https://www.ruby-lang.org/) and [Node.js](https://nodejs.org/) installed. Consult [our `.tool-versions` file](.tool-versions) for the versions that we use to validate and build in CI. This file is of particular use to those using [asdf](https://asdf-vm.com/) or compatible tooling.