clarify readme

[Bruno-366]

No description provided.

[erikmd]

Hi @Bruno-366, thanks for opening this!

I know that your PR is still in Draft mode, but I already left a few comments :)

BTW regarding my review comment w.r.t. the section title with action.yaml, do you think you could also add a comment such as the following somewhere (e.g. just after ## Example?) → feel free to rephrase anyway:

Using a GitHub Action in your GitHub repository amounts to committing a file .github/workflows/your-workflow-name.yml, e.g., .github/workflows/build.yml, containing (among others), a snippet such as:

runs-on: ubuntu-latest  # container actions require GNU/Linux
[…]
      ocaml_version: ${{ matrix.ocaml_version }}

Each field can be customized, see below for the documentation of those specific to the docker-coq-action, or the GitHub Actions official documentation for the standard fields involved in workflows.

[Bruno-366]

two questions: what is default value for export since its optional, and what language is custom_script (the mustaches)? custom_script expands to a bash script, but its written in something else (given that mustaches aren't part of bash). I suspect yaml.

[Bruno-366]

I think the remarks should maybe be moved so that they are before the inputs section, if reading them first makes understanding the inputs easier.

[Bruno-366]

Also the opam related information should have its own heading/section.
And maybe include a sentence like:

coq is built on-top of ocaml and so coq projects use ocaml's package manager (opam) to build themselves. This github action supports opam out of the box.

[erikmd]

I think the remarks should maybe be moved so that they are before the inputs section, if reading them first makes understanding the inputs easier.

Indeed, why not.

[erikmd]

Also the opam related information should have its own heading/section.

but there's already #### OPAM (?)

or maybe, you just mean move this section with a higher heading, such as ## OPAM ?

And maybe include a sentence like:

coq is built on-top of ocaml and so coq projects use ocaml's package manager (opam) to build themselves. This github action supports opam out of the box.

👍 good idea; you can commit this as is :) (maybe just capitalizing GitHub Action)

[erikmd]

@Bruno-366

two questions: what is default value for export since its optional,

It's true that the current doc https://github.com/coq-community/docker-coq-action/tree/v1.2.3#export only mentions one example with a single variable, so this can be misleading.

To be more precise:

• export needs to satisfy the regexp ^[a-zA-Z_][a-zA-Z0-9_ ]*$,
• it is intended to be a space-separated list of environment variables.
• If it is not passed to docker-coq-action, it just defaults to '', i.e., no additional variable is exported.

− However note that there's an open feature wish suggesting to change the behavior (a.k.a. needing to make each extra export explicit) to some "automatic, implied export of everything": #54 − but I've not yet decided how to deal with this suggestion (being safe/reliable, backward-compatible, and intuitive…)

and what language is custom_script (the mustaches)?

Good question 😉 → it's regular bash, plus some handcrafted support for specific mustaches expressions, as implemented by this code: https://github.com/coq-community/docker-coq-action/blob/v1.2.3/entrypoint.sh#L140-L153

The overall idea being to provide a GitHub container action (docker-coq-action) that works out-of-the-box with docker-coq / opam,
but also can do anything else if we want (using Docker images of, say Java :), while being customizable in two ways:

• either "in a Travis or so way", customizing all the parts that are implied in the custom_script (install:, script:, etc.), and keeping the default custom_script as is,
• or overriding the custom_script in a specific way (so, with a Bash script without relying on mustaches → ignoring then the other fields install:…)

[Bruno-366]

Also the opam related information should have its own heading/section.

but there's already #### OPAM (?)

or maybe, you just mean move this section with a higher heading, such as ## OPAM ?

And maybe include a sentence like:

coq is built on-top of ocaml and so coq projects use ocaml's package manager (opam) to build themselves. This github action supports opam out of the box.

👍 good idea; you can commit this as is :) (maybe just capitalizing GitHub Action)

I meant there is the information under remarks, and then there is the information at the top. There isn't really a good reason for splitting them up like that, given that both texts are so short, unless the plan is to add substantial more information under remarks.

[Bruno-366]

just a tip: the table can be added to the other repos and the x on the first column moved to the relevant row.

[erikmd]

I took the opportunity to refine a few other details in the markdown documentation; will squash-merge now.
Thanks again, @Bruno-366 !

[erikmd]

just a tip: the table can be added to the other repos and the x on the first column moved to the relevant row.

FYI @Bruno-366, this is now done :)

• https://github.com/coq-community/docker-base#readme
• https://github.com/coq-community/docker-coq#readme