Move the features specification to this repository

[QuintinWillison]

In the features/ folder readme added in ably/ably-common#142 this task is mentioned in the section headed 'Future Direction for the Client Library Features Specification' (once that PR lands, that section should be visible here).

The work required to complete this task is, as I see it...

1. Create copy in this repository

Copy current state of features.textile from ably/docs and commit it to this repository, in the features/ folder, with a logical file name for its new home - I would suggest sdk-specification.textile.

In the commit (via a PR) that adds this new file to this repository, include in the message a reference to the SHA it was copied over from in the docs repository. Likely HEAD of the main (default) branch. This may come handy in the future. 😉

2. Add GitHub workflow to render

It should be relatively trivial to use textile tools (probably Ruby-based, I guess, akin to what's used in the docs repository currently) to transform sdk-specification.textile to HTML so that it can be pushed to sdk.ably.com using our standard structure and mechanism.

3. Transfer issues

Issues that currently reside in the docs repository with the client-lib-spec label need to be transferred to this repository with a similar label, or perhaps something more appropriate (and less abbreviated 😉). FYI, @deanna-lad

4. Redirect visitors to the docs site

Coordinating with the docs team, replace the contents of features.textile in ably/docs with something explaining that it has moved. This should include a pointer to the new source location as well as the new rendered location. FYI, tbedford Srushtika

┆Issue is synchronized with this Jira Uncategorised by Unito

[lawrence-forooghian]

Do we also want to have a step for creating / documenting the workflow for running the static site locally, similar to what is described in https://github.com/ably/docs#quickstart?

And if we do that, I wonder how we'd handle links from the features spec to other parts of the docs site, e.g.

*** @(RSH1b3)@ @#save(device)@ issues a @PUT@ request to "/push/deviceRegistrations/:deviceId":/api/rest-api#update-device-registration

[QuintinWillison]

Thanks, @lawrence-forooghian, that's a good point. We will hit that hurdle when working on this task and the answer will hopefully present itself - which could be as simple as some kind of once-only mutation of the textile file to convert these from relative to absolute links.

[QuintinWillison]

This issue has a duplicate, created last year, so the comments in that issue should be considered when working on this issue. They both could be closed by the work done under this issue.

[QuintinWillison]

Once this issue has been worked on then we will also need to update this: https://github.com/ably/engineering/blob/main/sdk/versioning.md#features-specification-and-protocol-versioning

[QuintinWillison]

When assessing this features spec change PR, which I think clearly sits in the patch category from a SemVer perspective, being a clarification to an existing spec point - it reminded me that this guidance should be moved to this repository when this issue is worked on.

[QuintinWillison]

The change made to implement this issue must also include an equivalent to https://github.com/ably/docs/blob/main/scripts/find-duplicate-spec-items

[QuintinWillison]

See also: #2 (comment)

[QuintinWillison]

The initial content copy and Git commit history regeneration has now been done, with notes as to 'How' added as repository content here (it might be useful for future).

This issue will not be closed, however, until the content has been replaced in ably/docs with something that points visitors to here.

[QuintinWillison]

Before closing this issue, we should ensure that this pull request has been merged: ably/docs#1608