# Workflow

The main repo has two branches of interest: "master" (stable) and "develop" (in progress).
There might be other feature branches, but they are not relevant to this process.

Once "develop" is ready for a new release, the general workflow is to

release prep (`admin/release <version> <qualifier>`)...
- create a "release" branch from develop
- update version dependencies or constants
- generate version(s) of the user guide
- move or ignore stuff, distinguishing release from development
- test that all is as it should be
- merge the release branch into "master" & "develop"

After these have been vetted ...
- push the release(s) to github (`admin/release-deploy <version> <qualifier>`)
- **manually** create the release & tag it on GitHub, based on master  
  Include any supplementary binaries as part of releases.
- Confirm the GitHub release action successfully deploys `appstarter` and `framework`
- **manually** post a sticky announcement thread on the forum
- **manually** tweet the release announcement

## Assumptions

You (a maintainer) have forked the main CodeIgniter4 repo,
and the git alias `origin`, in your local clone, refers to your fork. 
The `config` script defines an additional alias, `CI_ORG`, which refers to the 
CodeIgniter 4 organization on github. 
This separation keeps the release branch isolated for any testing you want to do.

The `develop` branch of the main repo should be "clean", and ready for
a release. This means that the changelog and upgrading instructions
have been suitably edited.

This script is not intended to deal with hotfixes, i.e. PRs against
`master` that need to also be merged into `develop`, probably
as part of a bug fix minor release.

## GitHub Action

There is an action defined to run on any release publish event:
**.github/workflows/deploy.yml**. This will cascade any release made from
the main repo to the distribution repos, `appstarter` and `framework`. In order
for the action to authenticate you must create a Personal Access Token and add it
as a repo secret `ACCESS_TOKEN`. It is recommended that the PAT be to a secure bot
account with organization access that is dedicated for this purpose.

If for some reason a release needs to be made that should not cascade the easiest
solution is to disable repo actions temporarily.

## Usage

Inside a shell prompt, in the project root:

    `admin/release version [qualifier]`

Nothing is pushed to the repo at this point. You have a chance to vet
the repository changes.

The "version" should follow semantic versioning, e.g. `4.0.6`, and the
version number should be higher than the current released one.

The "qualifier" argument is a suffix to add to the version
for a pre-release, e.g. `beta.2` or `rc.41`.

Examples:
- `admin/release 4.0.0 alpha.1` would prepare the "4.0.0-alpha.1" pre-release PR
- `admin/release 4.0.0` would prepare the "4.0.0" release PR
- `admin/release peanut butter banana` would complain and tell you to read these directions

Once you have vetted the `dist` folder inside your local repo, you
can merge & push everything with

    `admin/release-deploy please`

On github.com, create an appropriate release (or pre-release),
with any optional files from the root of `dist`.

## Release notes

On launch of a new release, a release notes post should be made in the
announcements subforum. The planned text for it (so it can be previewed
by admins) is in `admin/release_notes.bb`.

## Audience

These scripts are intended for use by framework maintainers,
i.e. someone with commit rights on the CI4 repositories.

You will be prompted for your github credentials and
GPG-signing key as appropriate.