Versioning specs

[alancleary]

At our last meeting we discussed versioning individual specs so we can evolve them over time and keep track of what's actually implemented. The point of this issue is to work out the details. Here's some thoughts to start the discussion:

• What should the version be? Semantic (MAJOR.MINOR.PATCH, e.g. 1.3.2) is pretty standard. You could also add a revision number if you want to indicate a prerelease version of the spec that needs review.
• How do we release a spec? I think taking the same approach as the microservices repo could work: Every time a microservice is released, a GitHub release is made with the tag and name of MICROSERVICE@vMAJOR.MINOR.PATCH, where MICROSERVICE is the name of the directory in the repo that the microservice lives in.
• How do we indicate the version in the spec? I think more generally we should create a template that all specs should use. This could include a section for the version, ideally towards the top.

Any thoughts on this will be much appreciated.

[sammyjava]

Sounds fine to me. I don't have very strong opinions about versioning, though. It is worth noting, perhaps, that InterMine has MAJOR.MINOR.PATCH versioning from Cambridge, and then I append an LIS number to indicate an LIS extension version of the given core mine version (5.1.0.3 is our current LIS version and I'm not sure that InterMine will ever go past 5.1.0, since there is no one working on it at Cambridge any longer).

[alancleary]

Thanks for bumping this @sammyjava. It would be nice to come to a decision on this sooner than later since there's a PR open to make changes to the gene search web component that aren't in the spec, i.e. the spec needs to be brought up to date and it would nice to know if/how we're going to version specs before proceeding.

[alancleary]

I'm going to add this to the agenda for this week's LIS/PB meeting since the changes to the gene search PR is about ready to merge.

[StevenCannon-USDA]

I have added a "Specification version" to the top of each of these specs. The section has notes below the semantic version to give something like a change history. See, for example, https://github.com/legumeinfo/website-ui-specs/blob/main/gene-search/README.md

(the version history is kind of long in that case, so I put it in a collapsible div.)

I haven't yet made a template; thought that I would get feedback on the layout and versioning pattern first.

[sammyjava]

I'd add an "Optional parameters" category to your template, which would hold stuff like the genus option in the lis-gene-search-element web component tag. I expect we'll specify optional parameters for the web components fairly often. I think those would be at least mentioned here since they affect the UI (e.g. providing genus disables the genus selector).

[alancleary]

I think this is nice, @StevenCannon-USDA. Here's a few comments that come to mind:

1. I don't think "Notes" in the "Specification version" section is necessary if "Details" is the only thing that's going to be under it.
2. "October 19: update spec version to 1.1.1..." should be "September 19..."
3. I don't think an "Optional parameters" section is necessary since this is a spec for the UI, rather than a spec for the minutia of the web component implementation; I think simply noting that some functionality is optional as you've done is sufficient
4. Related to (3), once a web component implements the UI spec, a link should be added to the web component's documentation page. For example, the gene search link would be https://legumeinfo.github.io/web-components/classes/user_components.LisGeneSearchElement.html. Non web component specs could similarly link to other relevant documentation, such as things that are implemented in the Jekyll theme.

[StevenCannon-USDA]

Thanks for review and suggestions, @sammyjava and @alancleary. I've made those changes. Will let one of you close this if you think this is good enough for now. (I'm not too excited about doing a template, since it's not difficult to follow an existing example spec and modify it as needed.)

[alancleary]

The gene search spec looks good to me. It looks like the trait search still needs to be updated, though. It has a "Notes" section instead of a "Details" section like the gene search spec, and I think the spec needs to be updated to specify a paginated table instead of a list for the same reasons we switched the gene search spec back to the default table.

[maxglycine]

I think the 3 point versioning sounds reasonable. I don’t know enough to offer an opinion on how and when to release a new version

[maxglycine]

On the issue of pagination, I think that searches that retrieved a large number of hits will be difficult to scroll through to get a sense of all the hits if the number of lines initially returned is small. Could you choose the number of lines you see like 10,20,100,250 per page?

[alancleary]

On the issue of pagination, I think that searches that retrieved a large number of hits will be difficult to scroll through to get a sense of all the hits if the number of lines initially returned is small. Could you choose the number of lines you see like 10,20,100,250 per page?

The number of results returned by a paginated search is not specified in the spec and is, in fact, set in your GraphQL code. This raises a good point, though, that we should have a spec for paginated search. Once the spec is in place, you would then request that users can select the number of results per page via a GitHub issue in this repo.

[StevenCannon-USDA]

The gene search spec looks good to me. It looks like the trait search still needs to be updated, though. It has a "Notes" section instead of a "Details" section like the gene search spec, and I think the spec needs to be updated to specify a paginated table instead of a list for the same reasons we switched the gene search spec back to the default table.

Thanks; I've made those changes.

[alancleary]

I'm in the process of tagging releases for any spec that currently has a version number in it. Someone speak up if any such spec shouldn't actually have a tagged release yet!

Edit: Nevermind. I see that issues are still open for the gene-function (#7) and pan-gene (#9) searches. I won't tag those releases until the issues are closed. The gene and trait search specs have been released!

[alancleary]

I'm going to close this issue since we actually have versioned specs now.