Publish OSLC Configuration Management Primer OP Note

[oslc-bot]

Summary

We need a document describing the motivation of the spec, and how to use it, with plenty of examples.

TODOs

• [ ] Fix the template https://github.com/oasis-tcs/tab-respec/issues/49

References

• @ndjc's initial link: https://jazz.net/gc/doc/scenarios
• https://www.w3.org/TR/rdf11-primer/
• https://open-services.net/resources/oslc-primer/

---

Migrated from https://issues.oasis-open.org/browse/OSLCCORE-95 (opened by @ndjc; previously assigned to @ndjc)

[chet-ensign]

@berezovskyi - just repeating what I put on the closed ticket - a Project Note is a perfectly acceptable output.

[berezovskyi]

During the call, we were debating how much CCM expertise do we expect. I am leaning towards nearly 0. I expect the implementer of the CCM spec have OSLC experience, maybe building simple OSLC servers with LyoD or plaing with the reference implementation and some change management / release engineering experience / PLM experience but not much beyond that. If you see RDF primer, they do not expect you to come having a fresh knowledge of the First Order Logic and Description Logic. I recall that during both OSLCfests we had people with extensive PDM/PLM expertise who could not understand CCM and CCM spec despite being one of our target groups.

@ndjc and others: I would also appreaciate if you have CCM 101 links that could get me up to speed in under 3-4 hours of effort (to some degree, of course).

[berezovskyi]

from @jamsden

We had talked about how OSLC config management related to the PLM view. We could also relate it to git/GitHub and EWM SCM. By showing how these different views on versioning and configuration management relate, we can leverage experience people may already have.

[berezovskyi]

@jamsden this is nice and all but I would first focus on introducing CCM to non-experts in the field and only afterwards exploring those PLM connections. Another thing we discussed in the meeting is that the primer is not an academic book and does not have to position itself and the source of truth on CCM but instead a simple summary of how the CCM spec approaches it. So, for example, the definitions of versions and baselines have to make sense in the OSLC CCM context, not to be universally true.

[berezovskyi]

Thank you @chet-ensign! We will most likely take a PSD ReSpec template and use that to produce a Project Note. If you have a Markdown template, that might make things even simpler.

[berezovskyi]

@jadelkhoury do you think it would make sense for you to begin by listing a few questions here or an outline of the primer you'd like to read? Or do you want @img and @DavidJHoney propose something?

[jadelkhoury]

Here a list of things I would find useful in such a primer

1. an explanation of the concepts in the specs (streams, baselines, config context, etc), and how they relate to each other. The specs is very exact about a listing of each of these terms. But unless you are an expert, it is hard to get an overview, and understand the overall model behind it all.

2. an explanation of Global vs. Local Configuration. What role does each play in a toolchain? Which kinds of tool should implement which part?

3. For someone trying to implement CCM for any given tool, a hands-on incremental introduction of the concepts

   • How to introduce simple linear version control
   • How to introduce branching
   • How to introduce baselines
   • etc.

The primer not have to be complete, but enough to get someone started on a more basic setup (whatever that can be.)

[jadelkhoury]

I'd hope that such a primer can be accompanied by a reference/sample implementation that matches the content in the primer. We can view it as a tutorial too.

Although Lyo does not (yet) support CCM, this could be a starting point to see how we can add such support.

[berezovskyi]

@jadelkhoury @img #445 has a simple template I put together in a few minutes to let you draft the note in Markdown while rendering it in a Respec template.

[berezovskyi]

This is an example why I think it would be helpful: 5dc7d36 (#445)

[berezovskyi]

And with MDX https://mdxjs.com/ sky is the limit, we can add interactive OSLC request examples in the future etc.

[jadelkhoury]

At this stage, I'd rather we use a blank sheet (markdown, or even MSWord :-0) and focus on the content instead.

[berezovskyi]

That's exactly what I proposed, that you fill out ccm-primer.md and we take care of the templates! Did you check my PR itself?

[jadelkhoury]

No. I don't have the mental capability to review, compile & link 14 files in my head. But if you tell me I can write in a blank primer.md file, then the rest doesn't matter.

[berezovskyi]

@DavidJHoney @jadelkhoury do you think the wiki draft is good enough for us to publish a first PN draft?

[DavidJohnHoney]

Completed some months ago.

[berezovskyi]

Keeping it open until it's published on OASIS archive.