RE: [tosca] Managing TOSCA type profiles in github

I generally like the proposed structures, with the following comments:

I would like to avoid using Section numbers in the names of the example templates. I used to do this in the Ubicity project, but since the spec tends to be reorganized fairly frequently, I ended up having to rename these things all the time. I finally gave up. I hope we can come up with a more âpermanentâ naming scheme.
I prefer âtosca-profilesâ rather than âcommunity-profilesâ. I think we need to qualify any profile name with the word âtoscaâ since there will be non-TOSCA repos in the OASIS github account.

Thanks,

Chris

From: Tal Liron <tliron@redhat.com>
Sent: Wednesday, January 29, 2020 9:16 AM
To: Chet Ensign <chet.ensign@oasis-open.org>
Cc: Chris Lauwers <lauwers@ubicity.com>; tosca@lists.oasis-open.org
Subject: Re: [tosca] Managing TOSCA type profiles in github

In my opinion we should make this as open as possible, so an open repo could be best -- though the owners should be TC members (who can approve pull requests). Open, open, open is the key to success. :)

As to some thoughts on file organization. I think we should have two repositories actually:

1. One repository called "specification" with examples for the spec (and possibly even the text of the spec itself -- I'll discuss in the near future how we can use git to manage working on that). This repo is a "source of truth" but not the "final truth", rather it is a tool for us to collaborate and test. From this repo we will pull out information into the spec's Word document, which is the definitive spec proposal.

The structure of the "specification" repo could look something like this:

/specifications/

/specifications/1.3/

/specifications/2.0/

/specifications/2.0/examples/

/specifications/2.0/examples/1.1.2.3.1/

Those numbers could refer to sections in the spec where the examples appear.

Note that rather than managing multiple versions of the spec by git branches and tags I think we should have a single branch that includes all the "legacy" stuff, too. This is useful for viewers to quickly get a sense of evolution and see the changes. Of course once a spec is approved we can create a tag to capture that final state. But, really, why not continue to make fixes even if the spec was approved? Remember, this repo is not the "final truth".

For example, let's say TOSCA 1.3 is approved and published by the TC, but a month later a user finds a mistake in one of our examples and submits a pull request to this repo. Hooray, that's a very good thing and we should accept it! This change is not an official TC-approved modification of the spec, but rather publishing it here is a convenient service that we can provide to the community to collect such corrections. The published TOSCA 1.3 spec would still have this error, and you can use the git tag to go back to that state if you really want to see that version.

2. Another repository called "community-profiles" to which, for starters, we will have the Simple Profile (possibly renamed to something else). The repo will have room for more contributions in the future. Maybe "serverless"? Note the use of "community" in the name to emphasize that there are not normative.

The structure of the "community-profiles" repo could look something like this:

/profiles/

/profiles/simple/

/profiles/simple/1.4/

/profiles/simple/1.4/profile.yaml

/profiles/simple/1.4/data.yaml

/profiles/simple/1.4/nodes.yaml

/profiles/simple/1.4/capabilities.yaml

...

For an example of how this would look exactly, this is how I did it in Puccini.

Why separate the profile into multiple files? Why not? :) It improves readability. I don't think the separation always has to be by types of types, it could really be anything that makes sense to that profile's domain. It could even have subdirectories. The only convention we should insist on here is that the root document be called "profile.yaml" so that an automated testing tool would know where to start.

Another idea is to add another directory level there to signify the source of the profile (this ties to our earlier discussion of namespace conventions for profiles), i.e.:

/profiles/

/profiles/oasis/simple/

/profiles/oasis/simple/1.4/

/profiles/acme/radio/

/profiles/acme/radio/1.0/

/profiles/acme/simple/

/profiles/acme/simple/1.0/

This structure makes it easier to avoid profile name collisions. For example, different organizations might want to name their profile "kubernetes" and we definitely don't want this repo to appear as if it is the place to decide who gets to claim that name. :)

By the way, this is a small note -- notice that in the Puccini profiles all the imports from "profile.yaml" are relative paths. Indeed, you could point your imports directly to the HTTP links in GitHub -- even to specific commits -- and it would work just fine. So GitHub is not just a profile editing tool, but also a profile distribution tool, at least for development and testing. E.g. to import the Kubernetes profile from a specific commit would be this URL:

https://raw.githubusercontent.com/tliron/puccini/079bbb0bfa74b67c4bbfa4929935278311e43020/assets/tosca/profiles/kubernetes/1.0/profile.yaml

The relative import paths should work there, and of course also work if the files are local, and of course also work if they are within a CSAR.

tosca message