Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Advertising a version of TAXII at a CSD level is not currently possible #49

Closed
jordan2175 opened this issue Feb 21, 2018 · 16 comments
Closed

Comments

@jordan2175
Copy link

Given the way we advertise the TAXII version via the API Root and Media Types, it is not clear how one would go about saying they are using TAXII 2.1 CSD01 for example.

@jordan2175
Copy link
Author

I propose that we look at changing the version parameter to be a string instead of a float so we can do "2.1-csd01" or "2.1-csd-01" or "2.1.1" where the 3rd digits is the CSD version.

@johnwunder
Copy link

This general idea makes sense to me but the proposed approach in the draft needs work. For example, it calls out CSD specifically when you can also have multiple CS versions for a given major.minor release. Does that matter? Also, that means 2.1 is a later release than 2.1.01, which is pretty unintuitive.

We need to discuss this one more.

@allant0
Copy link

allant0 commented Feb 23, 2018

I suggest we use a string with a normalized string structure.

..[-CSD][-WD]

and the version string always has major.minor.patch so that it makes it easy for systems to do version matching.

So 2.0 would be 2.0.0
working draft of 2.1.1 would be 2.1.1-WD
CSD of 2.1 would be 2.1.0-CSD

Without -CSD or -WD then it would be considered the CS version.

@allant0
Copy link

allant0 commented Feb 23, 2018

For weird reason the major.minor.patch stuff got edited out by github above.

major.minor.patch[-CSD][-WD]

@jordan2175 jordan2175 added this to the 2.1-CSD01 milestone Feb 27, 2018
@jordan2175
Copy link
Author

jordan2175 commented Feb 27, 2018

After thinking about this a lot more, here are some thoughts. One of the concerns I have is I think we need a strictly increasing version number. For example, we may release say 4 CSDs:
2.1.1-csd,
2.1.2-csd,
2.1.3-csd,
2.1.4-csd

and then we release a CS and it would have
2.1.1-cs or would it be 2.1.5-cs? Then what happens if we get public comments that require a material change we have to issue a new CSD. Would it be CSD05 or would it then be 2.1.5-csd or 2.1.6-csd? What happens if we need to issue multiple CSs, either based on the same CSD or on a different CSD?

I think this will be completely confusing for people. I mean, this all makes sense to us, in the TC, however, I am afraid people outside the TC will not know or understand the nuances of WD, CSD, CS, etc. They will not know which comes next.

A slightly over engineered solution would be to assign a number to each level of the OASIS process, then it would keep increasing.

WD01 = 2.1.1.1-wd
WD02 = 2.1.1.2-wd
CSD01 = 2.1.2.1-csd
CSD02 = 2.1.2.2-csd
CS01 = 2.1.3.1-cs
CS02 = 2.1.3.1-cs
OASIS Standard 01 = 2.1.4.1

A last option, the one I prefer, would be to decouple the OASIS process number from our advertised version numbers and also treat anything and everything that the TC does not classify as done as a "draft". Example:

WD01 = 2.1.1-draft
WD02 = 2.1.2-draft
CSD01 = 2.1.3-draft
CSD02 = 2.1.4-draft
CS01 = 2.1.5-draft
CS02 = 2.1.6-draft
CS03 (final version) = 2.1.7 OR if we went to a full OASIS standard instead of another CS, it would still be 2.1.7. Basically, once the TC says we are done and no longer going to work on that branch anymore. Now in the future if we decided to go back and add something, we would just go
CSD03 = 2.1.8-draft
CSD04 = 2.1.9-draft
CS (final) = 2.1.10

Basically the third value is ALWAYS increasing. All versions that are not classified as "done" by the TC will have a suffix of "-draft". We would also say that content must get to at least a CS before the TC can classify it as "done".

We would need to decide what happens if the TC wants to go to a full OASIS standard. Does the CS versions keep the "-draft" suffix until the full OASIS standard version is submitted ?

@MarkDavidson
Copy link

If we had 4 CSDs, I would rather see:

  • 2.1-CSD1
  • 2.1-CSD2
  • 2.1-CSD3
  • 2.1-CSD4

I think packing the draft number into the specs version number will be confusing for people.

@johnwunder
Copy link

I agree with @MarkDavidson that we should either:

  1. Just use 2.1 for all CSDs/CSs in the 2.1 series of releases (preferred)
  2. If we have to have different strings for different CSDs, use something obvious like "2.1-CSD01" or "2.1-draft1".

@jordan2175
Copy link
Author

@MarkDavidson @johnwunder please see my description right about yours. Do you not think it would be more confusing for the industry to have to figure out if 2.1-CSD2 or 2.1-CS1 was the most current version? The reason why I am proposing divorcing the versions from the OASIS terminology is to make it easier for people. The version number would always increase, regardless of the OASIS stage.

So for the following internal versions you would have the corresponding TAXII versions. Lets use an example where we do 3 CSDs then a CS, then get substantive changes from the TAB or public and have to do one more CSD and then another CS..

CSD01 = 2.1.1
CSD02 = 2.1.2
CSD03 = 2.1.3
CS01 = 2.1.4
CSD04 = 2.1.5
CS02 = 2.1.6
OASIS Standard 01 = 2.1.7

This way the versions always increase. There is no confusion. Now, if we wanted to add a suffix like "draft" or something to indicate that it was not yet final, I am also okay with that.

@terrymacdonald
Copy link

terrymacdonald commented Feb 28, 2018

After a long discussion with Bret Jordan on the slack channel I've come to a conclusion:

I think the important part of CSD is the 'Draft' bit. It is not a real specification until it is a "Committee Specification". People shouldn't expect reliable code UNTIL we have a full CS completed. My stance is that the CSD is a draft for what the final CS will look like. Therefore we each CSD should reflect what we intend the final version of what the CS would look like.

Additionally - this only affects the test code people are developing. Its only a small group of test users who will be in contact with each other for testing purposes, and are who all likely to know when the next CSD is being released, and can just ask each other which CSD they support. Plugfests can be specific in which CSD they are testing. That said, I do understand it is a problem for interoperability during testing, so I would like to propose a slight modification to the suggestions above.

After a discussion with Bret, I would like to propose the following versioning format:
TAXII 2.1 CSD01 = 2.1-draft01
TAXII 2.1 CSD02 = 2.1-draft02
TAXII 2.1 CS FINAL = 2.1

I would like to see:

  • The production TAXII version in the CS to be the same as the TAXII version specification we are using, so that when we have agreed the CS and it passes the public review feedback stages the standard TAXII version would be '2.1'
  • The production TAXII version should be used in the standards text as we do now.
  • For each CSD we have an additional block of highlighted text that specifically states something like "While this standard is being developed we use a temporary TAXII version per CSD to aid in testing. The temporary TAXII version for this CSD is '2.1-draft01' and any test software that implement this specific CSD MUST support the temporary TAXII version in addition to the standard TAXII version used above."

Cheers
Terry MacDonald
Cosive

@jordan2175
Copy link
Author

I am okay with Terry's proposal. @allant0 @johnwunder @MarkDavidson can you support this? The idea is we would use a "-draft##" suffix for everything up until we do the final CSD for CS publication. At that point we would switch the version to be just "2.1". Any follow-on changes that are needed from multiple CS releases or even if the public review / TAB forces us to go back and do one more CSD, those changes should be small enough that we can track them out-of-band.

@MarkDavidson
Copy link

I'm personally in favor of using the plain version string, e.g., version=2.1 for all CSDs, for the following reasons:

  1. I don't understand why the stated problem is important to solve - no supporting evidence has been given in this thread, just a problem statement and various proposed solutions.
  2. Each new CSD and CS will require code changes to content negotiation, which increases the chances of interoperability breaking. If the change had supporting arguments, then I might view this tradeoff as worthwhile.
  3. I don't think the community in general will support multiple CSDs at once, I see the community supporting the latest CSD/CS. For instance, I don't see testing multiple CSDs at a plugfest - I see us doing interop testing for just the most recent CSD or CS.

I guess my biggest concern is - why is this a problem worth solving? I can see drawbacks for the various solutions proposed, though I'm not able to reason whether or not there are benefits to them.

In terms of what I'd bring to a plugfest or use as a baseline for a vendor integration, I'd only bring something that implements the most recent CSD or CS, and I would not care one bit about compatibility with older CSDs.

I want TAXII 2.1 compatibility issues to arise when two vendors implement different CSDs/CSs, because that's how we'll move the fastest toward interoperable TAXII 2.1 implementations in the marketplace.

@johnwunder
Copy link

I tend to agree w/ Mark that we shouldn't do this. We shouldn't encourage code that implements old CSDs to hang around by dignifying it with its own content version.

That said, if we do decide to identify individual CSD versions, I think the naming structure outlined above (2.1-draft1, 2.1-draft2, 2.1) is good.

@jmgnc
Copy link

jmgnc commented Mar 1, 2018

I also agree w/ Mark. CSD should be short lived enough that it's not an issue. If you have troubles between your products because you're implementing the draft, then you know it's a problem because of the draft, and we shouldn't be solving draft issues in the final production spec that will become CS.

Now if there was guidance outside the CSD/CS that recommended people use this, that'd be a different story.

@terrymacdonald
Copy link

terrymacdonald commented Mar 1, 2018 via email

@emmanvg
Copy link

emmanvg commented Mar 1, 2018

I agree with Mark's reasons to not do this. Based on the recent email conversation and as mentioned by John-Mark and Terry, if we really need this for testing purposes. It might be better to define the version in a separate informal document for people that are building prototypes.

@jordan2175
Copy link
Author

Closing based on results from ballot.

@jordan2175 jordan2175 moved this from Unknown to Done in TAXII-2.1 Apr 15, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
No open projects
TAXII-2.1
  
Done
Development

No branches or pull requests

7 participants