cuddle-please/docs/getting-started.md

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

cargo install cuddle-please

or docker (not public yet)

docker run -v $PWD:/mnt/src -e CUDDLE_PLEASE_TOKEN=<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 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.

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 <personal-access-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='<personal-access-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 and keep a changelog.

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.

# 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 <personal-access-token>

It is quite important that the title of the release commit is chore(release): <something>. <something> will be the version of the release.

When it is merged, simply update the local repository and run the same command as above.

# 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 <personal-access-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 for all the different platforms.

Below is a snippet showing a drone-ci setup

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. 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.