Metadata-Version: 2.1
Name: c2cciutils
Version: 1.1.38
Summary: Common utilities for Camptocamp CI
Home-page: https://github.com/camptocamp/c2cciutils
Author: Camptocamp
Author-email: info@camptocamp.com
License: FreeBSD
Keywords: ci
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: safety (==1.10.3)
Requires-Dist: markdown-table (==2020.12.3)
Requires-Dist: python-magic (==0.4.27)
Requires-Dist: requests (==2.31.0)
Requires-Dist: markdown (==3.3.7)
Requires-Dist: editorconfig (==0.12.4)
Requires-Dist: google-api-python-client (==2.36.0)
Requires-Dist: google-auth-httplib2 (==0.1.1)
Requires-Dist: google-auth-oauthlib (==0.4.6)
Requires-Dist: ruamel.yaml (==0.17.40)
Requires-Dist: jsonschema (==4.4.0)
Requires-Dist: jsonschema-gentypes (==0.9.4)
Requires-Dist: node-vm2 (==0.4.5)
Requires-Dist: defusedxml (==0.7.1)
Requires-Dist: pipenv (==2022.1.8)
Requires-Dist: black (==24.3.0)
Requires-Dist: click (==8.0.4)
Requires-Dist: isort (==5.10.1)
Requires-Dist: twine (==3.8.0)
Requires-Dist: codespell (==2.1.0)
Requires-Dist: attrs (==21.4.0)
Requires-Dist: bleach (==4.1.0)
Requires-Dist: cachetools (==5.0.0)
Requires-Dist: certifi (==2023.7.22)
Requires-Dist: cffi (==1.15.1)
Requires-Dist: charset-normalizer (==2.0.12)
Requires-Dist: colorama (==0.4.6)
Requires-Dist: cryptography (==42.0.6)
Requires-Dist: distlib (==0.3.8)
Requires-Dist: docutils (==0.18.1)
Requires-Dist: dparse (==0.5.2)
Requires-Dist: filelock (==3.4.2)
Requires-Dist: google-api-core (==2.5.0)
Requires-Dist: google-auth (==2.6.6)
Requires-Dist: googleapis-common-protos (==1.54.0)
Requires-Dist: httplib2 (==0.20.4)
Requires-Dist: idna (==3.7)
Requires-Dist: importlib-metadata (==4.10.1)
Requires-Dist: importlib-resources (==5.4.0)
Requires-Dist: jeepney (==0.7.1)
Requires-Dist: keyring (==23.5.1)
Requires-Dist: mypy-extensions (==0.4.4)
Requires-Dist: oauthlib (==3.2.2)
Requires-Dist: packaging (==22.0)
Requires-Dist: pathspec (==0.9.0)
Requires-Dist: pip (==23.3.2)
Requires-Dist: pkginfo (==1.8.3)
Requires-Dist: platformdirs (==2.4.1)
Requires-Dist: protobuf (==3.19.6)
Requires-Dist: pyasn1 (==0.4.8)
Requires-Dist: pyasn1-modules (==0.2.8)
Requires-Dist: pycparser (==2.21)
Requires-Dist: pygments (==2.15.1)
Requires-Dist: pyparsing (==3.0.9)
Requires-Dist: pyrsistent (==0.18.1)
Requires-Dist: pyyaml (==6.0.1)
Requires-Dist: readme-renderer (==32.0)
Requires-Dist: requests-oauthlib (==1.3.1)
Requires-Dist: requests-toolbelt (==0.9.1)
Requires-Dist: rfc3986 (==2.0.0)
Requires-Dist: rsa (==4.8)
Requires-Dist: ruamel.yaml.clib (==0.2.8)
Requires-Dist: secretstorage (==3.3.3)
Requires-Dist: six (==1.16.0)
Requires-Dist: toml (==0.10.2)
Requires-Dist: tomli (==2.0.1)
Requires-Dist: tqdm (==4.66.3)
Requires-Dist: typing-extensions (==4.0.1)
Requires-Dist: unidecode (==1.3.8)
Requires-Dist: uritemplate (==4.1.1)
Requires-Dist: urllib3 (==1.26.18)
Requires-Dist: virtualenv (==20.13.4)
Requires-Dist: virtualenv-clone (==0.5.7)
Requires-Dist: webencodings (==0.5.1)
Requires-Dist: zipp (==3.7.0)

# C2C CI utils

Commands:

- `c2cciutils`: some generic tools.
- `c2cciutils-checks`: Run the checks on the code (those checks don't need any project dependencies).
- `c2cciutils-audit`: Do the audit, the main difference with checks is that it can change between runs on the same code.
- `c2cciutils-publish`: Publish the project.
- `c2cciutils-clean`: Delete Docker images on Docker Hub after corresponding branch have been deleted.
- `c2cciutils-google-calendar`: Tool to test the google credentials for calendar API and refresh them if needed. See `c2cciutils-google-calendar -h` for more information.

# New project

The content of `example-project` can be a good base for a new project.

# Secrets

In the CI we needs to have the following secrets::

- `HAS_SECRETS` to be set to 'HAS_SECRETS', to avoid error errors from dependabot and from external
  pull requests, already set globally on camtocamp organisation.
- `GOPASS_CI_GITHUB_TOKEN` and `CI_GPG_PRIVATE_KEY` required to initialise the gopass password store,
  the secrets axists in the camptocamp organisation but not shared on all project, then you should add
  your project to the shared list.

# Use locally, in the projects that use c2cciutils

Install it: `python3 -m pip install --user --requirement ci/requirements.txt`
Run the checkers: `c2cciutils-checks [--fix] [--stop] [--check CHECK]`
Dry run publish: `GITHUB_REF=... c2cciutils-publish --dry-run ...`

# Configuration

You can get the current configuration with `c2cciutils --get-config`, the default configuration depends on your project.

You can override the configuration with the file `ci/config.yaml`.

At the base of the configuration you have:

- `version`: Contains some regular expressions to find the versions branches and tags, and to convert them into application versions.
- `checks`: The checkers configuration, see `c2cciutils/checks.py` for more information.
- `audit`: The audit configuration, see `c2cciutils/audit.py` for more information.
- `publish`: The publish configuration, see `c2cciutils/publish.py` for more information.

Many actions can be disabled by setting the corresponding configuration part to `False`.

# Checks

The configuration profile consider we use a project with:

- Dependabot.
- The following workflows:
  - `Continuous integration`,
  - `Rebuild` on all supported branch,
  - `Audit` for security issues on all supported branches,
  - `Backport` between all supported branches,
  - `Clean Docker hub tags`,
  - `Auto merge Dependabot updates`.
- A `SECURITY.md` file.

It will check that:

- All the workflows are conform on what we expect,
- All the workflows are completely configured for all the versions present in `SECURITY.md` file.
- The code is conform with the `black` and `isort` rules.
- The `gitattributes` are valid.
- All text files end with an empty line.

# SECURITY.md

The `SECURITY.md` file should contains the security policy of the repository, espessially the end of
support dates.

For compatibility with `c2cciutils` it should contain an array with at least the columns
`Version` and `Supported Until`. The `Version` column will contain the concerned version.
The `Supported Until` will contains the date of end of support `dd/mm/yyyy`.
It can also contain the following sentences:

- `Unsupported`: no longer supported => no audit, no rebuild.
- `Best effort`: the support is ended, it is still rebuilt and audited but this can be can stopped without any notice.
- `To be defined`: not yet released or the date will be set related of an other project release date (like for GeoMapFish).

See also [GitHub Documentation](https://docs.github.com/en/github/managing-security-vulnerabilities/adding-a-security-policy-to-your-repository)

# IDE

The IDE should be configured as:

- using `black` and `isort` without any arguments,
- using the `editorconfig` configuration.

## VScode

- Recommend extensions to work well with c2cciutils:
  - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) And use EditorConfig
- Other recommend extensions:
  - [hadolint](https://marketplace.visualstudio.com/items?itemName=exiasr.hadolint)
  - [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)

Select a formatter:

- `CTRL+MAJ+P`
- Format document With...
- Configure Default Formatter...
- Select the formatter

# Publishing

## To pypi

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:

```python
VERSION = os.environ.get("VERSION", "1.0.0")
```

The config is like this:

```yaml
versions:
  # List of kinds of versions you want to publish, that can be:
  # rebuild (specified with --type),
  # version_tag, version_branch, feature_branch, feature_tag (for pull request)
```

## To Docker registry

The config is like this:

```yaml
latest: True
images:
    - name: # The base name of the image we want to publish
repository:
    <internal_name>:
        'server': # The fqdn name of the server if not Docker hub
        'version':# 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)
        'tags':# List of tags we want to publish interpreted with `template(version=version)`
            # e.g. if you use `{version}-lite` when you publish the version `1.2.3` the source tag
            # (that should be built by the application build) is `latest-lite`, and it will be published
            # with the tag `1.2.3-lite`.
        'group':# If your images are published by different jobs you can separate them in different groups
            # and publish them with `c2cciutils-publish --group=<group>`
```

By default the last line of the `SECURITY.md` file will be published (`docker`) with the tag
`latest`. Set `latest` to `False` to disable it.

With the `c2cciutils-clean` the images on Docker hub for `feature_branch` will be removed on branch removing.
