From decdf5f7777fa8ff20d97e58ecda96b00b9a9797 Mon Sep 17 00:00:00 2001 From: kjuulh Date: Wed, 2 Aug 2023 14:11:29 +0200 Subject: [PATCH] docs: add docs Signed-off-by: kjuulh --- docs/configuration.md | 81 +++++++++++++++++++++ docs/getting-started.md | 152 ++++++++++++++++++++++++++++++++++++++++ docs/index.md | 42 +++++++---- docs/installation.md | 29 ++++++++ mkdocs.yml | 4 ++ 5 files changed, 296 insertions(+), 12 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/getting-started.md create mode 100644 docs/installation.md diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..cf02e52 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,81 @@ +# Configuration + +`cuddle-please` requires configuration to function, it is quite flexible, and tries to help you as much as possible filling out values for you, or using sane defaults. + +First of all, you can either use the `cuddle.yaml` if using `cuddle`, or `cuddle.please.yaml` if using standalone. + +```yaml +# file: cuddle.yaml +please: + +--- +# file: cuddle.please.yaml +project: + owner: kjuulh + repository: cuddle-please + branch: main +settings: + api_url: https://git.front.kjuulh.io +``` + +This is all the configuration, most of these won't be needed when running in CI. + +`cuddle` fetches configuration items from different sources, each level is able to override the previous layer. + +1. Execution environment +2. Configuration files +3. Stdin +4. Env variables +5. Cli arguments +6. User input + +Lets break each down. + +### Execution environment + +Execution environment, is the environment under which cuddle-please is run, if running in CI, we're able to take some variables, without requiring input from the user, or configuration values. + +Right now only `drone-ci` is supported, but github actions and such, are nearly done. + +#### Drone CI + +Drone CI, will automatically fill out +```yaml +project: + owner: + repository: + branch: +``` + +This means that the only thing the user needs to configure is the `api_url` and the access `` + +### Configuration files + +Already shown above, this allows setting hard-coded values, especially useful for the `api_url`. + +### Stdin + +All the configurations can be passed via. stdin + +```bash +cat cuddle.please.yaml | cuddle-please release --stdin +``` + +### Env variables + +The CLI shows which env variables are available via. `cuddle-please release --help`. + +### CLI args + +The CLI shows which args are available via. `cuddle-please release -h # or --help` + +`-h` gives a shorthand description and `--help` provides a longer explanation of each arg. + +There are some args, which are exclusive to the cli or env variables, such as ``. This is because it is a secret and it shouldn't be leaked in the configuration. There are some exceptions such as `GITHUB_TOKEN` which is picked in the environment variable layer. + +### Interactive (User input) + +cuddle-please will determine whether or not it is running with a user interactive `stdin`, and will prompt for missing values if running locally. This is disabled without a proper tty, or if running in one of the CI execution environments by default. Otherwise `--no-interactive` can be passed to any command. + + + \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..de48ac6 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,152 @@ +# Getting started + +`cuddle-please` is a tool to manage releases in a git repository. + +It is either run manually or in ci. To get the most correct behavior +`cuddle-please` should be run on each commit on your primary branch +(main/master). + +## Install + +First you need the executable + +```bash +cargo install cuddle-please +``` + +or docker (not public yet) + +```bash +docker run -v $PWD:/mnt/src -e CUDDLE_PLEASE_TOKEN= kjuulh/cuddle-please:latest +``` + +!!! warning Other distributions to be added. + +## Configuration + +`cuddle-please` requires configuration to function, it is quite flexible, and +tries to help you as much as possible filling out values for you, or using sane +defaults. + +For this `getting-started` guide, we will use cli args, but see +[configuration](configuration.md) for all the other options, both manual, +automatic, and interactive. + +## Running + +First make sure you're on your release branch, this is likely either `main` or +`master`. + +```bash +git checkout main + +cuddle-please release \ +--engine gitea \ +--owner kjuulh \ +--repository cuddle-please \ +--branch main +--api-url 'https://git.front.kjuulh.io/kjuulh/cuddle-please' \ +--token \ +--dry-run +``` + +We use `gitea` backend here, but you can either leave it out (as it is default +gitea), or set it to github (once that is done). + +The token needs to have write access to your repository, as well as the api. +(guide tbd). + +Dry-run is used here to not commit any changes to your backend, it may still +change your local git setup, but not the backends. Simply remove the arg if you +want to commit. !!! note `--token` can also be set with +`export CUDDLE_PLEASE_TOKEN=''` if you don't want to leak +the secret to your cli history. + +When run you should get output that it has created a dry_run pull-request, +meaning that it was supposed to do the action but didn't commit it. + +If you've used versioning previously in your repository, i.e. a tag with +`v1.0.0` or `1.0.0` it will use that to bump the commits based on +[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) and +[keep a changelog](https://keepachangelog.com/en/1.1.0/). + +Changelog generation can be disabled with `--no-changelog`. + +### Merging the pr. + +If you've created the pull-request (i.e. with the dry-run arg). You can simply +just go to the pull-request and squash merge it. + +```bash +# showing the command again, now without --dry-run +# you were automatically moved to cuddle-please/release when running the above command +git checkout main + +cuddle-please release \ +--engine gitea \ +--owner kjuulh \ +--repository cuddle-please \ +--branch main +--api-url 'https://git.front.kjuulh.io/kjuulh/cuddle-please' \ +--token +``` + +It is quite important that the title of the release commit is +`chore(release): `. `` will be the version of the release. + +When it is merged, simply update the local repository and run the same command +as above. + +```bash +# you were automatically moved to cuddle-please/release when running the above command +git checkout main +git pull origin main + +cuddle-please release \ +--engine gitea \ +--owner kjuulh \ +--repository cuddle-please \ +--branch main +--api-url 'https://git.front.kjuulh.io/kjuulh/cuddle-please' \ +--token \ +``` + +You should now see a release artifact in the releases page, as well as a tag +with the version. + +### Running in CI. + +Cuddle-please shines the best when running in CI, as we're able to pull most +variables from that, such as `owner`, `repository`, `branch`, etc. + +To run in ci see [continuous-integration](continuous-integration.md) for all the +different platforms. + +Below is a snippet showing a `drone-ci` setup + +```yaml +kind: pipeline +name: cuddle-please-release +type: docker + +steps: + - name: cuddle-please release + image: docker.io/kjuulh/cuddle-please:v0.1.0 + commands: + - cuddle-please release + environment: + CUDDLE_PLEASE_TOKEN: + from_secret: cuddle-please-token + CUDDLE_PLEASE_API_URL: "https://git.front.kjuulh.io" + when: + branch: + - main + - master +``` + +All the other options will automatically be pulled from the drone environment. +Throughts its own +[runtime configuration](https://docs.drone.io/pipeline/environment/reference/). +Right now only drone is supported with these fetch features, Please open an +issue, if you have another environment you'd like to run in. Such as github +actions, circleci, etc. diff --git a/docs/index.md b/docs/index.md index 000ea34..115ac1d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,35 @@ -# Welcome to MkDocs +# Cuddle docs -For full documentation visit [mkdocs.org](https://www.mkdocs.org). +Cuddle Please is an extension to `cuddle`, it is a separate binary that can be executed standalone as `cuddle-please`, or in cuddle as `cuddle please`. -## Commands +The goal of the software is to be a `release-please` clone, targeting `gitea` instead of `github`. -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. +The tool can be executed as a binary using: -## Project layout +```bash +cuddle please release # if using cuddle +# or +cuddle-please release # if using standalone +``` - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. +And when a release has been built: + +```bash +cuddle please release +# or +cuddle-please release +``` + +cuddle will default to information to it available in git, or use a specific entry in `cuddle.yaml` called + +```yaml +# ... +please: + name: + # ... +# ... +``` + +or as `cuddle.please.yaml` + +See docs for more information about installation and some such diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..7f881e0 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,29 @@ +# Installation + +## Cargo version + +```bash +cargo install cuddle-please +# or +cargo binstall cuddle-please # if using binstall +``` + +More to come as the project matures. + +## Development version + +### Cuddle + +[Cuddle](https://git.front.kjuulh.io/kjuulh/cuddle) is a script and configuration management tool, it is by far the easiest approach for building the development version of cuddle-please, but optional. + +```bash +cuddle x build:release +# or docker +cuddle x build:docker:release +``` + +### Cargo + +```bash +cargo build --release -p cuddle_cli +``` diff --git a/mkdocs.yml b/mkdocs.yml index 87fac82..0faf388 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,3 +19,7 @@ theme: toggle: icon: material/brightness-4 name: Switch to light mode # Palette toggle for light mode +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences \ No newline at end of file