What structure for the Tooling repository?

[Kevsy]

Tooling does not produce APIs, so the usual 'API repository' structure is not the best fit. Rather it is closer to a 'Working group' and could have a specific structure to allow development/testing/publication of tools.

In #4 we discuss which tasks to focus on. Some of these tasks will be best done remotely (i.e. via a GitHub workflow), some may be best done locally (e.g. a pre-commit hook, or importing latest Commonalities/ICM info and schema artefacts ).

So the repository structure could reflect the tasks, e.g. (to be agreed in #4 ):

tooling
/development
/validation
/security
/testing
/release management

...and in each sub-directory, distinguish between local and remote tools (if applicable).

Note this structure is intended to make development of the tools easier. But we also need to make it easy for the CAMARA API developers (our customers :)) to use, so the release should make it easy to find and use the artefacts - so maybe adding an 'artefacts' directory with documentation.

WDYT?

[Kevsy]

Tagging @hdamker for welcome advice :)

[hdamker]

Just my few cents:

• you have to consider how you are doing release or at least tag management for the repository. A release or tag is always across the complete repository, so the different folders aren't independent.
• What to you mean with "local" and "remote" tools?
• Wouldn't the top level with /code and /documentation still make sense? /artifacts could also make sense, but my understanding is that you aren't replacing the artifacts from Commonalities here?
• My understanding is that the reusable workflows finally have to be in /.github/workflows to be (re)usable. This directory can't have subdirectories (lot of people asked for that, but GitHub never implemented).

[Kevsy]

Thanks Herbert:

you have to consider how you are doing release or at least tag management for the repository. A release or tag is always across the complete repository, so the different folders aren't independent.

Yes - it's arguably a similar situation in Commonalities. Your suggestion for a simpler /code /documentation structure should help.

What to you mean with "local" and "remote" tools?

local = repository on the API editor's local machine, remote = the GitHub repository. Checks and validation can be performed either local and remote, but corrective actions (e.g. trim trailing whitespace and save the result, importing the latest info templates and artefacts ) are easier done local before committing. It would be useful to find out how the CAMARA API editors build the APIs, e.g. only using github.com and 'edit file' in the browser, or using editor.swagger.io, or VisualStudio locally etc. . Because then we can know whether 'local' tools are in scope, and/or whether we should in fact recommend a blend of local and remote tools for most impact.

Wouldn't the top level with /code and /documentation still make sense? /artifacts could also make sense, but my understanding is that you aren't replacing the artifacts from Commonalities here?

Yes, top level /code /documentation is fine. We should not need artefacts in that case as tools can be placed in 'code', or referenced in documentation (in the case that 3rd party local tools are recommended)

My understanding is that the reusable workflows finally have to be in /.github/workflows to be (re)usable. This directory can't have subdirectories (lot of people asked for that, but GitHub never implemented).

Yes, good point.

[rartych]

So the repository structure could reflect the tasks, e.g. (to be agreed in #4 ):

tooling
/development
/validation
/security
/testing
/release management

I took this approach in my initial proposal in https://github.com/rartych/xCAMARA-tooling
For linting task:

  /linting
   /config   #configuration files for various linters + custom function definitions
   /docs     # more formally can be named documentation
   /workflows  #caller workflows to be copied into subprojects /.github 

The reusable workflows need to be placed in .github/workflows folder of the tooling repositiory

So the folders for each task are almost self-contained.

Let's figure out how to do the releases/versioning to minimize the actions needed from subprojects.

The default/current definitions and configurations can be in the main branch.
We can think of development branch to test new things.
And if subproject needs to use older version then it should reference to release branches.
I will check again if that works for now.

[Kevsy]

Let's figure out how to do the releases/versioning to minimize the actions needed from subprojects

Yes, that's important.

For now we can research if there is a demand for other tools in addition to linters. If there is a demand for authoring tools - and an easy way to get them used by codeowners - then we can look at where we can make their materials/documentation available.