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

```bash
cargo install cuddle-please
```

or docker (not public yet)

```bash
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](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 <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](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 <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.

```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 <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](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.