ohdf — archive

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

From: Stefan Hagen
To: [email protected]
Date: Sat, 15 Apr 2023 15:02:00 -0000

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: [email protected] <[email protected]> on behalf of Stefan Hagen <[email protected]> Date: Friday, April 14, 2023 at 3:43 PM To: [email protected] <[email protected]> Cc: Mike Fraser <[email protected]>, Aaron L Lippold <[email protected]> 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: [email protected]