Merge pull request #23 from camptocamp/doc

Better schema metadata

.github/publish.yaml

@@ -2,12 +2,12 @@
 
 pypi:
   versions:
-    - version_tag
-    - version_branch
+    - tag
+    - stabilization_branch
+    - default_branch
   packages:
     - {}
 docker:
-  auto_login: true
   images:
     - name: camptocamp/tag-publish
 helm:

.github/spell-ignore-words.txt

@@ -1,2 +1,4 @@
 pypi
 Snyk
+github
+publish.yaml

.github/workflows/main.yaml

@@ -80,6 +80,10 @@ jobs:
 
       - run: docker build --tag camptocamp/tag-publish tests
 
+      - name: Publish dry-run
+        run: poetry run tag-publish --dry-run
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Publish
         run: poetry run tag-publish
         env:

README.md

@@ -5,7 +5,7 @@
 The main goals of Tag Publish offer the commands to publish the project,
 Using a tag, a stabilization branch, a feature branch or a pull request.
 
-When possible it can do a secret-less publishing, if it's not possible the login should be done before the publishing.
+When possible it can do a secret-less publishing (privileged in defaults), if it's not possible the login should be done before the publishing.
 
 See the [documentation](https://github.com/camptocamp/c2cciutils/wiki/Publishing).
 
@@ -41,6 +41,10 @@ Do the publishing:
 
 ## New version
 
+To create a new version you should create a Git tag with the version number.
+
+## New stabilization branch
+
 To create a new minor version you just should run `tag-publish-new --version=<version>`.
 
 This will create the stabilization branch and will create a new pull request to update
@@ -54,6 +58,17 @@ Note that it didn't create a tag, you should do it manually.
 
 To create a patch version you should just create tag.
 
+## Kind of publishing
+
+This tool can publish on different kind of versions:
+
+- `tag`: Related to a Git tag.
+- `default_branch`: Related to the default branch.
+- `stabilization_branch`: Related to a stabilization branch (including the default branch).
+- `feature_branch`: Related to a feature branch or a pull request.
+
+We can also publish on different kind of versions like `rebuild` by using the `--type` argument.
+
 ## SECURITY.md
 
 The `SECURITY.md` file should contain the security policy of the repository, especially the end of
@@ -94,7 +109,7 @@ https://docs.github.com/en/actions/security-for-github-actions/security-hardenin
 
 By default the package will be published only on tag, if you want to publish on stabilization branch you should add
 a `versions` key with the list of versions you want to publish, that can be:
-`rebuild` (specified with --type), `version_tag`, `version_branch`, `feature_branch`, `feature_tag` (for pull request)
+`rebuild` (specified with --type), `tag`, `default_branch`, `stabilization_branch`, `feature_branch`, `pull_request` (for pull request merge: number)
 
 It we have a `setup.py` file, we will be in legacy mode:
 When publishing, the version computed from arguments or `GITHUB_REF` is put in environment variable `VERSION`, thus you should use it in `setup.py`, example:
@@ -113,8 +128,10 @@ enable = true
 vcs = "git"
 pattern = "^(?P<base>\\d+(\\.\\d+)*)"
 format-jinja = """
-{%- if env.get("VERSION_TYPE") == "version_branch" -%}
-{{serialize_pep440(bump_version(base, 1 if env.get("IS_MASTER") == "TRUE" else 2), dev=distance)}}
+{%- if env.get("VERSION_TYPE") == "default_branch" -%}
+{{serialize_pep440(bump_version(base, 1), dev=distance)}}
+{%- elif env.get("VERSION_TYPE") == "stabilization_branch" -%}
+{{serialize_pep440(bump_version(base, 2), dev=distance)}}
 {%- elif distance == 0 -%}
 {{serialize_pep440(base)}}
 {%- else -%}
@@ -124,7 +141,7 @@ format-jinja = """
 
 ```
 
-Note that we can access to the environment variables `VERSION`,`VERSION_TYPE` and `IS_MASTER`.
+Note that we can access to the environment variables `VERSION`,`VERSION_TYPE`.
 
 Then by default:
 
@@ -185,13 +202,13 @@ docker:
 If you want to use the GitHub token to be logged in on ghcr you should set `auto_login` to `True`, the
 requires the permissions are `packages: write`.
 
-With that the image initially named `camptocamp/tag-publish:latest` will be published on GitHub CHCR and on Docker hub.
+With that the image initially named `camptocamp/tag-publish:latest` will be published on GitHub GHCR and on Docker hub.
 
 The full config is like this:
 
 ```yaml
 docker:
-  auto_login: False
+  github_oidc_login: True
   latest: True
   images:
     - # The base name of the image we want to publish
@@ -201,7 +218,7 @@ docker:
       # The fqdn name of the server if not Docker hub
       server:
       # List of kinds of versions you want to publish, that can be: rebuild (specified using --type),
-      # version_tag, version_branch, feature_branch, feature_tag (for pull request)
+      # tag, stabilization_branch, feature_branch, pull_request (for pull request merge: number)
       version:
       # List of tags we want to publish interpreted with `format(version=version)`
       # e.g. if you use `{version}-lite` when you publish the version `1.2.3` the source tag
@@ -279,7 +296,7 @@ This will create a repository dispatch of type `published` on own repository wit
 ```json
 {
   "version": "1.2.3",
-  "version_type": "version_tag",
+  "version_type": "tag",
   "repository": "camptocamp/tag-publish",
   "items": [
     {

config.md

@@ -1,20 +1,21 @@
-# configuration
+# Tag publish configuration
 
-_Tag Publish configuration file_
+_Tag Publish configuration file (.github/publish.yaml)_
 
 ## Properties
 
-- **`version`** _(object)_: The version configurations.
-  - **`branch_to_version_re`**: Refer to _[#/definitions/version_transform](#definitions/version_transform)_.
-  - **`tag_to_version_re`**: Refer to _[#/definitions/version_transform](#definitions/version_transform)_.
+- **`transformers`** _(object)_: The version transform configurations. Default: `{"pull_request_to_version_re": [{"to": "pr-\\1"}]}`.
+  - **`branch_to_version`**: Refer to _[#/definitions/transform](#definitions/transform)_.
+  - **`tag_to_version`**: Refer to _[#/definitions/transform](#definitions/transform)_.
+  - **`pull_request_to_version`**: Refer to _[#/definitions/transform](#definitions/transform)_.
 - **`docker`**: Refer to _[#/definitions/docker](#definitions/docker)_.
 - **`pypi`**: Refer to _[#/definitions/pypi](#definitions/pypi)_.
 - **`node`**: Refer to _[#/definitions/node](#definitions/node)_.
 - **`helm`**: Refer to _[#/definitions/helm](#definitions/helm)_.
 - **`dispatch`** _(array)_: Default: `[]`.
   - **Items** _(object)_: Send a dispatch event to an other repository. Default: `{}`.
     - **`repository`** _(string)_: The repository name to be triggered. Default: `"camptocamp/argocd-gs-gmf-apps"`.
-    - **`event-type`** _(string)_: The event type to be triggered. Default: `"published"`.
+    - **`event_type`** _(string)_: The event type to be triggered. Default: `"published"`.
 
 ## Definitions
 
@@ -26,41 +27,41 @@ _Tag Publish configuration file_
       - **`name`** _(string)_: The image name.
       - **`tags`** _(array)_: The tag name, will be formatted with the version=<the version>, the image with version=latest should be present when we call the tag-publish script. Default: `["{version}"]`.
         - **Items** _(string)_
-  - **`repository`** _(object)_: The repository where we should publish the images. Can contain additional properties. Default: `{"github": {"server": "ghcr.io", "versions": ["version_tag", "version_branch", "rebuild"]}}`.
+  - **`repository`** _(object)_: The repository where we should publish the images. Can contain additional properties. Default: `{"github": {"host": "ghcr.io", "versions_type": ["tag", "default_branch", "stabilization_branch", "rebuild"]}}`.
     - **Additional properties** _(object)_
-      - **`server`** _(string)_: The server URL.
-      - **`versions`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["version_tag", "version_branch", "rebuild", "feature_branch"]`.
+      - **`host`** _(string)_: The host of the repository URL.
+      - **`versions_type`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["tag", "default_branch", "stabilization_branch", "rebuild", "feature_branch", "pull_request"]`.
         - **Items** _(string)_
-  - **`auto_login`** _(boolean)_: Auto login to the GitHub Docker registry. Default: `false`.
+  - **`github_oidc_login`** _(boolean)_: Auto login to the GitHub Docker registry. Default: `true`.
 - <a id="definitions/pypi"></a>**`pypi`** _(object)_: Configuration to publish on pypi.
   - **`packages`** _(array)_: The configuration of packages that will be published.
     - **Items** _(object)_: The configuration of package that will be published.
       - **`group`** _(string)_: The image is in the group, should be used with the --group option of tag-publish script. Default: `"default"`.
       - **`folder`** _(string)_: The folder of the pypi package. Default: `"."`.
       - **`build_command`** _(array)_: The command used to do the build.
         - **Items** _(string)_
-  - **`versions`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["version_tag"]`.
+  - **`versions_type`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["tag"]`.
     - **Items** _(string)_
 - <a id="definitions/node"></a>**`node`** _(object)_: Configuration to publish on node.
   - **`packages`** _(array)_: The configuration of packages that will be published.
     - **Items** _(object)_: The configuration of package that will be published.
       - **`group`** _(string)_: The image is in the group, should be used with the --group option of tag-publish script. Default: `"default"`.
       - **`folder`** _(string)_: The folder of the node package. Default: `"."`.
-  - **`versions`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["version_tag"]`.
+  - **`versions_type`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["tag"]`.
     - **Items** _(string)_
-  - **`repository`** _(object)_: The packages repository where we should publish the packages. Can contain additional properties. Default: `{"github": {"server": "npm.pkg.github.com"}}`.
+  - **`repository`** _(object)_: The packages repository where we should publish the packages. Can contain additional properties. Default: `{"github": {"host": "npm.pkg.github.com"}}`.
     - **Additional properties** _(object)_
-      - **`server`** _(string)_: The server URL.
+      - **`host`** _(string)_: The host of the repository URL.
   - **`args`** _(array)_: The arguments to pass to the publish command. Default: `["--provenance"]`.
     - **Items** _(string)_
 - <a id="definitions/helm"></a>**`helm`** _(object)_: Configuration to publish Helm charts on GitHub release.
   - **`packages`** _(array)_: The configuration of packages that will be published.
     - **Items** _(object)_: The configuration of package that will be published.
       - **`group`** _(string)_: The image is in the group, should be used with the --group option of tag-publish script. Default: `"default"`.
       - **`folder`** _(string)_: The folder of the pypi package. Default: `"."`.
-  - **`versions`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["version_tag"]`.
+  - **`versions_type`** _(array)_: The kind or version that should be published, tag, branch or value of the --version argument of the tag-publish script. Default: `["tag"]`.
     - **Items** _(string)_
-- <a id="definitions/version_transform"></a>**`version_transform`** _(array)_: A version transformer definition.
+- <a id="definitions/transform"></a>**`transform`** _(array)_: A version transformer definition. Default: `[]`.
   - **Items** _(object)_
-    - **`from`** _(string)_: The from regular expression.
-    - **`to`** _(string)_: The expand regular expression: https://docs.python.org/3/library/re.html#re.Match.expand.
+    - **`from_re`** _(string)_: The from regular expression. Default: `"(.+)"`.
+    - **`to`** _(string)_: The expand regular expression: https://docs.python.org/3/library/re.html#re.Match.expand. Default: `"\\1"`.

pyproject.toml

@@ -93,8 +93,10 @@ enable = true
 vcs = "git"
 pattern = "^(?P<base>\\d+(\\.\\d+)*)"
 format-jinja = """
-{%- if env.get("VERSION_TYPE") == "version_branch" -%}
-{{serialize_pep440(bump_version(base, 1 if env.get("IS_MASTER") == "TRUE" else 2), dev=distance)}}
+{%- if env.get("VERSION_TYPE") == "default_branch" -%}
+{{serialize_pep440(bump_version(base, 1), dev=distance)}}
+{%- elif env.get("VERSION_TYPE") == "stabilization_branch" -%}
+{{serialize_pep440(bump_version(base, 2), dev=distance)}}
 {%- elif distance == 0 -%}
 {{serialize_pep440(base)}}
 {%- else -%}