Re: [ohdf] Motion to request a GitHub TC repository for Specification Work Products

["Stefan Hagen" <stefan@hagen.link>]

Thanks a lot, Duncan.

My rationale on suggesting a single repo to start with and as baseline is twofold:

First, In my experience splits cause complexity and are best avoided if no actual itch has to be scratched.

- If and when the need arises, we can always add a specialized repo to the TC portfolio.

  The new "stuff" should provide already a good name postfix to "ohdf" because of the

  very reason it does not fit into the single repo.

Second, In the repository planning I take on a systems perspective (looking from the end towards the beginning):

Namely, the docs.oasis-open.org place offers the A_TC/A_SPEC/A_VERSION 3-level hierarchy and this hierarchy

is where all our work products will end / fit in.

As an example https://docs.oasis-open.org/csaf/ holds the work products from the CSAF TC

as folders/directories:

1. csaf/v.2.0/ (for now providing CSAF v2.0) and

2. csaf-cvrf/v1.2/ (which provides "kind of CSAF" v1.2).

In CSAF we profited IMO a lot from simplifying the work area by only having a single csaf GitHub TC repo.

We split also in there by folders. Examples matching the two target work products named above:

1. https://github.com/oasis-tcs/csaf/tree/master/csaf_2.0

2. https://github.com/oasis-tcs/csaf/tree/master/cvrf_1.2

Every such folder can provide  the needed supportive sub-ordering per folders like (from the CSAF v2.0 example):

- comment_resolution (to progress after public reviews)

- examples (examples for different aspects of the XSAF eco system)

- json_schema (the machine readable JSON schema files being part of the spec)

- prose (the spec in markdown format - source)

- register (names at IANA)

- submit (OS to ISO.)

- test (holding test data and possibly test code supporting e.g. GitHub actions for CI/CD quality checks inside PRs)

Keeping minutes, issues, peer-reviews, prose, schema files, test data etc. in a single place

helps a lot to ease referencing and also minimizes the hassle contributors have to go through

for providing input.

One thing that in my experience is annoying for authors of even meeting minute drafts let alone

spec / schema changes is that one can only add the GitHub contributors to that repo (CLA signed) to

pull requests instead of those members that regularly contribute enhancing comments.

On the other hand, anyone worldwide (that has a GitHub account ) can simply add themselves as

reviewers to PRs and approve or comment any foo bar bar quux (if we keep the repository perms

open and reasonable).

Splitting the work places across multiple repos multiplies that cost in any case.

All the best,

Stefan.

On Sat, Apr 15, 2023, at 16:17, duncan sfractal.com wrote:

I seconded the motion but I would recommend âthisâ repo be the âadminâ repo (meeting minutes, etc) and that you make separate repoâs  for each future work product.

So for example someone could contribute âOHDC Schemaâ to this repo (maybe in an âincomingâ direcgory) with a PR just to get over the CLA requirements, but after looking at the contrib people think âthis rates being a CSDâ, then I think a new repo should be made just for that CSD. One repo/work product makes the administrivia easier, makes it easier for people to find what then want (albeit I also think the home page of the admin repo should have link to everything with explanation of what is where) and only work on what they want, and ties âgithub releasesâ to âspec versionsâ in a more logical way (you can do it if multiple specs in one repo, but itâs very confusing, at least to me).

 

-- 

Duncan Sparrell

sFractal Consulting

iPhone, iTypo, iApologize

I welcome VSRE emails. Learn more at http://vsre.info/

 

 

 

From: ohdf@lists.oasis-open.org <ohdf@lists.oasis-open.org> on behalf of Stefan Hagen <stefan@hagen.link>
Date: Friday, April 14, 2023 at 3:43 PM
To: ohdf@lists.oasis-open.org <ohdf@lists.oasis-open.org>
Cc: Mike Fraser <Mike.Fraser@sophos.com>, Aaron L Lippold <alippold@mitre.org>
Subject: [ohdf] Motion to request a GitHub TC repository for Specification Work Products

Dear TC members,

 

I hereby submit the following motion and request that if seconded and no objection received per this list

before one week has passed on 2023-04-21 20:00 UTC to automatically carry.

 

Note: For seconding this motion it is sufficient to reply to this message on the TC list

and add the word "second" or "seconded".

 

The Secretary or Co-Chairs usually state the result per mail to this list when the period has passed.

 

I, Stefan Hagen, hereby move that the TC requests from OASIS administration the creation 

of the Github repository https://github.com/oasis-tcs/ohdf to manage spec related work products like

schema files, specification prose, test files, minutes of meeting, issues, peer reviews, IANA requests and others.

 

I further move, that the initial maintainers shall be Aaron Lippold and Stefan Hagen.

 

When this motion carries, the secretary will submit the relevant form such that OASIS

administration can create the repository and enable the maintainers access.

 

PS: We can always add or change maintainers later easily.

 

All the best,

Stefan.

 

...

 

Stefan Hagen, Emmetten, Nidwalden, Switzerland.

orcid: https://orcid.org/0000-0003-4206-892X

read: https://stefan-hagen.website

write: stefan@hagen.link