oasis-tcs / openc2-tc-ops Goto Github PK

OASIS OpenC2 TC: Documentation associated with TC operations and information sharing such as FAQs, lists of links to related work, and norms for developing and approving TC work products. https://github.com/oasis-tcs/openc2-tc-ops

License: Other

openc2-tc-ops's Introduction

README

🗨️ Description 🗨️

This repository is for documentation associated with the OASIS OpenC2 TC's operations and information sharing such as FAQs, lists of links to related work, and norms for developing and approving TC work products. Given the intent of the repo, both TC co-chairs and the secretary are maintainers.

The OpenC2.org website has an FAQ list.

🗺️ What's Here? 🗺️

This repository includes the following information:

General-Member-Info.md -- An overview of how the OpenC2 TC conducts its operations; useful for both new and existing members
An OpenC2 Companion -- a friendly, informal guide to all of the pieces of OpenC2 and how you put them together to do something useful (a really good place to start)
JADN and OpenC2 -- A concise introduction to Information Modeling and the JSON Abstract Data Notation (JADN) IM language, including the use of JADN in defining and documenting the OpenC2 information model
Documentation-Norms.md -- An information document for work product editors, including the TC's use of markdown and GitHub for developing and managing those work products. Also includes information about choosing work products names and shorthands, branch management strategy for work product GitHub repos, and other helpful info.
Work-Product-List.md -- a list of the TC's on-going work products with status, editor names, links to repositories and recent versions
Working-Meeting-Process.md -- a description of the new (as of March 2021) process for planning and conducting working meetings to advance the development of work products in the OpenC2 TC
Meeting-Scheduling.md -- notes about the meeting scheduling process, for reference by co-chairs and the TC secretary
Document-Template-2020.md -- a highly condensed version of the new work product outline adopted in late 2020 by OASIS. New work items should use this format (it will be reflected in the starter document provided by OASIS). Existing work items can be reformatted to use this outline; the TC's work product editors consider it an improvement.
Other-OpenC2-Work.md -- a listing of OpenC2 implementation efforts known to the TC outside of those maintained in open repositories sponsored by the TC
ITU Process For OpenC2 Adoption -- a wiki page with information about the International Telecommunications Union (ITU) and efforts to encourage its adoption of OpenC2 as an ITU Recommendation.

OASIS-Controlled Repository

Members of the OASIS Open Command and Control (OpenC2) TC create and manage technical content in this TC GitHub repository (https://github.com/oasis-tcs/openc2-tc-ops/) as part of the TC's chartered work (the program of work and deliverables described in its charter.

OASIS TC GitHub repositories, as described in GitHub Repositories for OASIS TC Members' Chartered Work, are governed by the OASIS TC Process, IPR Policy, and other policies. While they make use of public GitHub repositories, these repositories are distinct from OASIS Open Repositories, which are used for development of open source licensed content.

✍️ Contributions ✍️

As stated in this repository's CONTRIBUTING file, contributors to this repository must be Members of the OASIS OpenC2 TC for any substantive contributions or change requests. Anyone wishing to contribute to this GitHub project and participate in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the OASIS Feedback License.

📜 Licensing 📜

Please see the LICENSE file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the OpenC2 TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository LICENSE.

📩 Contact 📩

Please send questions or comments about OASIS TC GitHub repositories to the OASIS TC Administrator. For questions about content in this repository, please contact the TC Co-Chairs or Secretary as listed on the the OpenC2 TC's home page.

openc2-tc-ops's People

Contributors

Stargazers

Watchers

Forkers

vasileios-mavroeidis sparrell sthagen stickyfloors dlemire60

openc2-tc-ops's Issues

GitHub Maintainers

Documentation norms should have something about github maintainers. Include:

how OASIS staff retains admin rights for whatever it is they can do that we can't
that maintainers are assigned based on TC role and cochairs, secretary, and work product editors all become maintainers by definition
actually giving the maintainer role is one of the OASIS staff functions (ie only staff can actually update github to add or delete a maintainer)
reference https://www.oasis-open.org/maintainers-guide/ for the OASIS guide for maintainers
the repo should contain the names of the maintainers in the readme and/or contributing file

Documentation Norms: missing information

A Bret Jordan comment on the original Google Doc, not addressed prior to the MD conversion:

What I find missing in this document are the following:

How you are handling actual changes that people have. Typically people read through a document and make comments or suggestions all over the place. However, when you do a "git add and git push" and then a Pull Request, you get all of them as a single thing.

How do you accept part of them and not the rest?

How do you handle the processing of Pull Requests?

How do you take and address comments on other people's pull requests?

How do you get consensus on whether to accept a pull request or not?

I could not find where any of this is called out in the document.

Documentation Norms: capturing editable sources for images

In an appendix to Documentation Norms (EDIT, 8/3/2022, updated link: https://github.com/oasis-tcs/openc2-tc-ops/blob/main/Documentation-Norms.md#c3-creating-images-and-editable-sources) it's suggested to create a folder in the document repo to hold editable image sources (e.g., /src). There are a some special cases where we might want to provide more explicit guidance:

Downloaded images from Diagrams.net (formerly Draw.io) embed an editable version of the image within the PNG, JPEG, etc. You can upload the image and Diagrams.net will extract the editable content and allow you make changes. So the image is its own editable source, but that's not true for raster formats generally. One solution is to place a copy of the image in both /images and /src. Another possibility is a naming convention to convey info about the file, e.g., image1.ddn.png (where DDN = diagrams dot net).
Text sources that drive image generators like PlantUML. The generated image should go in the /images folder, as normal. The text source can go into the /src folder, but some indication is needed of where that source can be used. Potential approaches are:

A comment in the text identifying the associated generator
A naming scheme similar to the suggestion in item #1 (e.g., image1.plant.txt
An index file in the /src folder associating text files with generators

For Google Draw images, need a general way of documenting the URL (and owning account?) of the image source.

There might be other cases I haven't thought of.

DocNorms: Creating a WD, TOC creation tools

Documentation Norms Section 4.4.1 says that pandoc can be used to generate a markdown table of contents. Although pandoc will do that (and much more), installing it solely for the purpose of generating a TOC is overkill. There are millions of markdown TOC generator plugins for various editors and we can't mention them all, but it would be useful to note that that editor plugins are a lightweight alternative.

For vscode I'm using Markdown All in One, (which has 1.8 million installs and 5 star reviews).

Generating and previewing the TOC directly in an editor is very convenient, and deserves a mention in Norms.

Master to Main

The document should be updated to reflect the new norm of using 'main' instead of 'master' for the default branch

GitHub Branches and Releases

We discussed GitHub release management at the Feb 2 TC working meeting.

Should the GitHub Published branch include CSDs?

The Kavi TC page has folders for

Approved Work Products (CS, CSD, and OASIS Standards) published by OASIS Staff
Working Drafts published by TC members (TC Secretary or document editors)

The OASIS public Standards page lists CS and OS documents but not CSDs.

Reasonable arguments can be made for both approaches - CSDs published by OASIS are "published" and belong in the Published branch, or CSDs published by OASIS are still Drafts and belong in the Working branch. Depending on the day of the week I could prefer either approach. Yesterday I liked CSD + CS so users get the latest OASIS docs when they look at the default branch. Today I like the current CS-only approach so users see the latest "stable official" version by default. Naming the default branch "published" may be part of the problem; it might more clearly represent CS-only if it were called "stable", or even just "main".

Should GitHub include final versions edited for publication by OASIS staff?

In my opinion, yes. The CS or CSD documents we submit to OASIS for publication are still working documents even if we remove WDxx from the name before submitting. Only documents edited by OASIS are "official". We should discuss with Chet/Paul whether they should remove the WDxx as part of their publication process, since anything created by the TC and committed to GitHub is by definition a WD.

How should working versions be numbered

In my opinion, once OASIS publishes a document as "Version 1.0 CS01" we should immediately commit it to GitHub as the baseline for the next version "Version 1.1 CSD01 WD00". "Version 1.1 CSD01 WD01" would then be our first commit towards that next version. If we found non-material changes / errata, we would commit them as "Version 1.0 CS02 WD01" (or "Version 1.0.1 WD01" if OASIS chooses to replace CS numbers with SemVer).

Should OASIS adopt Semantic Versioning?

We should discuss with Chet/Paul whether OASIS might adopt SemVer numbering so there is never a Version 1.0 CS02. A document with only non-material changes from a Major.Minor version would be published as a Major.Minor.Patch number (Version 1.0.1) with no CS number. That would certainly make the Standards page easier to read, since only Version numbers are visible, not CS numbers.

Documentation Norms: Establish document title norms

Proposed: over-arching documents (e.g., Language Specification, Architecture) should spell out OpenC2 in their titles. Supporting documents (e.g., actuator profiles and transfer specs) don't need to do so as they are dependent on the overarching documents.

Examples:

Open Command and Control (OpenC2) Language Specification
Open Command and Control (OpenC2) Architecture Specification
OpenC2 Actuator Profile for cyberfunction
OpenC2 Transfer Specification for protocol