fix(#303): Update README with compatibility info

[wooldridge]

Fixes #303

[jmakeig]

How does a user know which features are new in 2.0.1, other than the README? (JSDoc, for example, has @since)

Do we need to add any more specifics on the 8.-? Just saying “8” is certainly simpler than “8.x-y”, if it’s possible.

[wooldridge]

@ayuwono, what's the easiest way to run Node.js Client API tests on the earliest and latest versions of ML8? I would like to substantiate that the upcoming release works on all versions of 8, and proving that it works on the earliest and latest would be strong proof of this. I've actually already run the tests on 8.0-6.3, so what I'm really looking for is the first version of ML8.

[wooldridge]

@jmakeig, here's what we get in the current docs generation when we use @since):

It would be great to add that info across the API docs. It would take some sleuthing to determine each method came into being.

[kcoleman-marklogic]

At this stage, you can probably get away with tagging everything with 1.0, except what's new in 2.0-1. The whole API was new for 8.0-1, and while there were a few functional changes (like being able to pass multiple URIs to Documents.remove), I don't think any new functions or interfaces were added in 8.0-x.

The thing I always wonder about with a feature like this (we get requests for the XQuery docs, too) is what is the contract, really? Like in the example I gave above, Documents.remove was there from the beginning, but had its functionality extended. Does that get a version bump or not? Just one of those "inquiring minds want to know" things. :)

[ayuwono]

@wooldridge, are you looking for the earliest version of ML8 (like 8.0-6.1)? You can find it at /project/engineering/builds/

[jmakeig]

At this stage, you can probably get away with tagging everything with 1.0, except what's new in 2.0-1.

@kcoleman-marklogic, that sounds like a great idea. We can refine the precision later to specific signatures, but this would be a great start.

[wooldridge]

I've updated the JSDoc information with @since tags. All methods and namespaces are marked version 1.0 except for the following (which are marked 2.0.1):

documents.protect()
documents.wipe()
documents.protectResult()
documents.wipeResult()
patchBuilder.patchBuilderMetadataValues
patchBuilderMetadataValues.add()
patchBuilderMetadataValues.remove()
patchBuilderMetadataValues.replace()
queryBuilder.falseQuery()
queryBuilder.geospatialRegion()
queryBuilder.minDistance()
queryBuilder.trueQuery()
queryBuilder.MinDistanceParam

[wooldridge]

I also updated the README to specify that 2.0.1 has been tested successfully with 8.0-6.3 and 9.0-1, which is true. I discussed this with @ehennum, and he said this aligns with the rolling upgrade requirements for the client APIs: MarkLogic must offer clients that work with the latest release of the current version (e.g. 9.0-1) and the latest release of the previous version (e.g. 8.0-6.3).

Erik and I also discussed the need for specifying version compatibility with each our tests for more efficient testing of API compatibility with MarkLogic versions. I could then run 2.0.1 on ML 8.0-6.3 and have it skip the tests for new features in 9.0-1.

[wooldridge]

I'm going to merge this and close the associated issue (#303). We can fine tune the README as @jmakeig prepares release notes (#327).