diff --git a/admin/README.md b/admin/README.md index 1f5dd89bfcd1..8f06a6282e22 100644 --- a/admin/README.md +++ b/admin/README.md @@ -43,45 +43,30 @@ This folder contains tools or docs useful for project maintainers. ## Maintainer Scripts -- **release-config** holds variables used for the maintainer & release building - **docbot** re-builds the user guide from the RST source for it, and optionally deploys it to the `gh-pages` branch of the main repository (if the user running it has maintainer rights on that repo). See the [writeup](./docbot.md). -## Release Building Scripts +## Release Scripts -*Do not use these scripts! They are left here for reference only.* - -The release workflow is detailed in its own writeup; these are the main -scripts used by the release manager: - -- **release** builds a new release branch in the main repo, for vetting. - This includes updating version dependencies or constants, - generating version(s) of the user guide; and possibly - moving or ignoring stuff, distinguishing release from development. - If successful, it will update the `config` file, with the version number - in it, and it will run the related scripts following, to revise - the release distributions. - Usage: `admin/release version qualifier` -- **release-userguide** builds the distributable userguide repo. - It could be used on its own, but is normally part of `release`. -- **release-deploy** pushes the release changes to the appropriate github - repositories. Tag & create releases on GitHub. This is not easily reversible! - Usage: `admin/release-deploy version qualifier` -- **release-revert** can be used to restore your repositories to the state they - were in before you started a release. **IF** you haven't deployed. - This is in case you decide not to proceed with the release, for any reason. - Remember to be polite when running it. +The release process is detailed in [RELEASE.md](./RELEASE.md). These scripts +are used as part of that process: +- **prepare-release.php** creates the `release-4.x.x` branch and updates + version references in the framework source, the user guide, and the + distribution build script. + Usage: `php admin/prepare-release.php 4.x.x` +- **create-new-changelog.php** creates the changelog and upgrade guide + stubs for the next version and adds them to their index files. + Usage: `php admin/create-new-changelog.php ` ## Other Stuff -- **release-notes.bb** is a boilerplate for forum announcements of a new release. - It is marked up using [BBcode](https://en.wikipedia.org/wiki/BBCode). - The **framework** and **starter** subfolders contain files that will over-ride those from the development repository, when the distribution repositories are built. - The subfolders inside `admin` contain "next release" files in the case of `codeigniter4` and over-written distribution files in the other cases. -- The CHANGELOG.md file is auto-generated using the [GitHub Changelog Generator](https://github.com/github-changelog-generator/github-changelog-generator) +- The CHANGELOG.md file is generated from GitHub's auto-generated release + notes, as described in [RELEASE.md](./RELEASE.md). diff --git a/admin/RELEASE.md b/admin/RELEASE.md index 75b4e26b2b31..a6b3f680b6ad 100644 --- a/admin/RELEASE.md +++ b/admin/RELEASE.md @@ -18,17 +18,18 @@ ## Merge `develop` branch into next minor version branch `4.y` -Before starting release process, if there are commits in `develop` branch that +Before starting the release process, if there are commits in `develop` branch that are not merged into `4.y` branch, merge them. This is because if conflicts occur, merging will take time. -```console -git fetch upstream -git switch 4.y -git merge upstream/4.y -git merge upstream/develop -git push upstream HEAD -``` +* [ ] Merge `develop` into `4.y`: + ```console + git fetch upstream + git switch 4.y + git merge upstream/4.y + git merge upstream/develop + git push upstream HEAD + ``` ## [Minor version only] Merge minor version branch into `develop` @@ -118,16 +119,16 @@ the existing content. * Create a new branch `release-4.x.x` * Update **system/CodeIgniter.php** with the new version number: `const CI_VERSION = '4.x.x';` - * Update **user_guide_src/source/conf.py** with the new `version = '4.x'` (if releasing - the minor version) and `release = '4.x.x'`. + * Update **user_guide_src/source/conf.py** with the new `version = '4.x'` + and `release = '4.x.x'`. * Update **user_guide_src/source/changelogs/{version}.rst** * Set the date to format `Release Date: January 31, 2021` * Update **phpdoc.dist.xml** with the new `CodeIgniter v4.x API` and `` * Update **admin/starter/builds**: * Set `define('LATEST_RELEASE', '^4.x')` - * Set `define('NEXT_MINOR', '4.y-dev')`. - * If the major version changes, you need to manually change to `define('NEXT_MINOR', '5.0-dev')`. + * Set `define('NEXT_MINOR', '^4.y-dev')`. + * If the major version changes, you need to manually change to `define('NEXT_MINOR', '^5.0-dev')`. * Commit the changes with `Prep for 4.x.x release` * [ ] Create a new PR from `release-4.x.x` to `develop`: * Title: `Prep for 4.x.x release` @@ -234,26 +235,31 @@ sudo pip3 install sphinx_rtd_theme ### Manual User Guide Process -* Still in the **CodeIgniter4** repo enter the **user_guide_src** directory -* Clear out any old build files: `rm -rf build/` -* Build the HTML version of the User Guide: `make html` -* Build the ePub version of the User Guide: `make epub` -* Switch to the **userguide** repo and create a new branch `release-4.x.x` -* Replace **docs/** with **CodeIgniter4/user_guide_src/build/html** -* Ensure the file **docs/.nojekyll** exists or GitHub Pages will ignore folders +> [!NOTE] +> This process is normally not needed. The "Deploy Distributable Repos" action +> builds and deploys the User Guide automatically when a release is published. +> Follow these steps only if the automatic deployment fails. + +* [ ] Still in the **CodeIgniter4** repo enter the **user_guide_src** directory +* [ ] Clear out any old build files: `rm -rf build/` +* [ ] Build the HTML version of the User Guide: `make html` +* [ ] Build the ePub version of the User Guide: `make epub` +* [ ] Switch to the **userguide** repo and create a new branch `release-4.x.x` +* [ ] Replace **docs/** with **CodeIgniter4/user_guide_src/build/html** +* [ ] Ensure the file **docs/.nojekyll** exists or GitHub Pages will ignore folders with an underscore prefix -* Copy **CodeIgniter4/user_guide_src/build/epub/CodeIgniter.epub** to +* [ ] Copy **CodeIgniter4/user_guide_src/build/epub/CodeIgniter.epub** to **./CodeIgniter4.x.x.epub** -* Commit the changes with "Update for 4.x.x" and push to origin -* Create a new PR from `release-4.x.x` to `develop`: +* [ ] Commit the changes with "Update for 4.x.x" and push to origin +* [ ] Create a new PR from `release-4.x.x` to `develop`: * Title: "Update for 4.x.x" * Description: blank -* Merge the PR -* Create a new Release: +* [ ] Merge the PR +* [ ] Create a new Release: * Version: "v4.x.x" * Title: "CodeIgniter 4.x.x User Guide" * Description: "CodeIgniter 4.x.x User Guide" -* Watch for the "github pages" Environment to make sure the deployment succeeds +* [ ] Watch for the "github pages" Environment to make sure the deployment succeeds The User Guide website should update itself via the deploy GitHub Action. Should this fail the server must be updated manually. See repo and hosting details in diff --git a/admin/release b/admin/release deleted file mode 100755 index d14167f0502e..000000000000 --- a/admin/release +++ /dev/null @@ -1,145 +0,0 @@ -#!/bin/bash - -## Build framework release branch & distributables - -# Setup variables -. admin/release-config - -echo -e "${BOLD}${COLOR}CodeIgniter4 release builder${NORMAL}" -echo '----------------------------' - -#--------------------------------------------------- -# Check arguments -echo -e "${BOLD}Checking arguments...${NORMAL}" - -if [ $# -lt 1 ]; then - echo -e "${BOLD}Usage: admin/release version# pre-release-qualifier${NORMAL}" - exit 1 -fi - -#--------------------------------------------------- -# Create the release branch -echo -e "${BOLD}Creating $which $branch to $action ${NORMAL}" - -git checkout develop -git branch -d $branch &>/dev/null # remove the branch if there -git checkout -b $branch -composer update - -#--------------------------------------------------- -# Update version dependencies -echo -e "${BOLD}Updating version dependencies${NORMAL}" - -function check_unique { - count=`grep -c '$1' < $2 | wc -l` - if [ $count -ne 1 ]; then - echo -e "${BOLD}${COLOR}$2 has ${count} occurrences of '$1'${NORMAL}" - exit 1 - fi -} - -# Make sure there is only one line to affect in each file -check_unique "const CI_VERSION" 'system/CodeIgniter.php' -check_unique "release =" 'user_guide_src/source/conf.py' -check_unique "|release|" 'user_guide_src/source/changelogs/index.rst' -check_unique "Release Date.*Not Released" 'user_guide_src/source/changelogs/index.rst' - -# CI_VERSION definition in system/CodeIgniter.php -sed -i "/const CI_VERSION/s/'.*'/'${RELEASE}'/" system/CodeIgniter.php - -# release substitution variable in user_guide_src/source/conf.py -sed -i "/release =/s/'.*'/'${RELEASE}'/" user_guide_src/source/conf.py - -# version & date in user_guide_src/source/index.rst -sed -i "/|release|/s/|.*|/${RELEASE}/" user_guide_src/source/changelogs/index.rst -sed -i "/Release Date/s/Not Released/$(date +'%B %d, %Y')/" user_guide_src/source/changelogs/index.rst -sed -i "/|version|/s/|version|/${RELEASE}/" user_guide_src/source/changelogs/index.rst - -# version & date in user_guide_src/source/next.rst -sed -i "/Release Date/s/Not Released/$(date +'%B %d, %Y')/" user_guide_src/source/changelogs/next.rst -sed -i "/|version|/s/|version|/${RELEASE}/" user_guide_src/source/changelogs/next.rst - -# establish version-specific changelog -sed -i "|changelogs/next|s|changeslog/next|changelogs/v{$RELEASE}|" user_guide_src/source/changelogs/index.rst -mv user_guide_src/source/changelogs/next.rst user_guide_src/source/changelogs/v${RELEASE}.rst -touch user_guide_src/source/changelogs/next.rst -cp admin/next.rst user_guide_src/source/changelogs/next.rst - -#--------------------------------------------------- -# Setup the distribution folders -echo -e "${BOLD}Building distribution folders${NORMAL}" - -function setup_repo { - echo -e "${BOLD}... $1${NORMAL}" - if [ -d dist/$1 ]; then - rm -rf dist/$1 - fi - mkdir dist/$1 - cd dist/$1 - git init - git remote add origin ${CI_ORG}/$1.git - git fetch - git checkout master - git checkout -b $branch - cd $CI_DIR -} - -if [ -d dist ]; then - rm -rf dist/ -fi -mkdir dist - -setup_repo userguide - -#--------------------------------------------------- -# Housekeeping - make sure writable is flushed of test files -# at least, test files that crop up on my system :-/ -rm -f writable/cache/H* -rm -f writable/cache/d* -rm -f writable/cache/s* -rm -f writable/debugbar/debug* -rm -f writable/logs/log* - -#--------------------------------------------------- -# Generate the user guide -echo -e "${BOLD}Generate the user guide${NORMAL}" - -cd user_guide_src - -# make the UG -rm -rf build/* -echo -e "${BOLD}... HTML version${NORMAL}" -make html -touch build/html/.nojekyll -echo -e "${BOLD}... epub version${NORMAL}" -make epub - -cd ${CI_DIR} - -# add changelog preamble -file=user_guide_src/source/changelogs/index.rst -sed -i "4 a Version |version|" $file -sed -i "5 a ====================================================" $file -sed -i "6 G" $file -sed -i "7 a Release Date: Not Released" $file -sed -i "8 G" $file -sed -i "9 a **Next release of CodeIgniter4**" $file -sed -i "10 G" $file -sed -i "11 G" $file -sed -i "12 a :doc:\`See all the changes. \`" $file -sed -i "13 G" $file - -#--------------------------------------------------- -echo -e "${BOLD}Commit the release branch${NORMAL}" -git add . -git commit -S -m "Release ${RELEASE}" - -#--------------------------------------------------- -# Build the distributables - -. admin/release-userguide - -#--------------------------------------------------- -# Done for now -echo -e "${BOLD}Your $branch branch is ready to inspect.${NORMAL}" -echo -e "${BOLD}Follow the directions in workflow.md to continue.${NORMAL}" diff --git a/admin/release-config b/admin/release-config deleted file mode 100644 index 8a969af81c68..000000000000 --- a/admin/release-config +++ /dev/null @@ -1,26 +0,0 @@ -# Variables used for release building - -if [ -z "$CI_ORG" ]; then - - # Initialize variables - CI_ORG=https://github.com/codeigniter4 - CI_DIR=`pwd` - - BOLD='\033[1m' - NORMAL='\033[0m' - COLOR='\033[1;31m' - ERROR='\033[0;31m' - - qualifier= - which=release - - version=$1 - if [ $# -gt 1 ]; then - qualifier="-${2}" - which='pre-release' - fi - - RELEASE=$version$qualifier - branch="release-$RELEASE" - -fi diff --git a/admin/release-deploy b/admin/release-deploy deleted file mode 100755 index fe70284024fc..000000000000 --- a/admin/release-deploy +++ /dev/null @@ -1,31 +0,0 @@ -#!/bin/bash - -## Push local changes to github - -echo -e "${BOLD}${COLOR}CodeIgniter4 release deployment${NORMAL}" -echo '-------------------------------' - -. admin/release-config - -echo -e "${BOLD}Merge release into develop${NORMAL}" -git checkout develop -git merge $branch -git push origin develop -git push ${CI_ORG}/CodeIgniter4 develop - -echo -e "${BOLD}Merge develop into master${NORMAL}" -git checkout master -git merge develop -git push origin master -git push ${CI_ORG}/CodeIgniter4 master - -echo -e "${BOLD}Pushing to the user guide repository${NORMAL}" -cd ${CI_DIR}/dist/userguide -git push origin master - -cd ${CI_DIR} - -#--------------------------------------------------- -# Phew! -echo -e "${BOLD}Congratulations - we have liftoff${NORMAL}" -echo "Don't forget to announce this release on the forum and on twitter!" diff --git a/admin/release-notes.bb b/admin/release-notes.bb deleted file mode 100755 index 6147a011cde1..000000000000 --- a/admin/release-notes.bb +++ /dev/null @@ -1,43 +0,0 @@ -CAUTION: THIS FILE IS A MIX OF BBCODE & MARKDOWN... NEEDS PROOFING - -CodeIgniter-4.0.0-alpha.1 launches today, after a lengthy build-up :) - -Huge shoutout to Lonnie Ezell for all of his hard work getting the vision -and the core implementation in place! - -This is an early pre-release of 4.0.0. It is not suitable for production! - -There are several possible downloads, that you can see on the -[url=https://github.com/codeigniter4/CodeIgniter4/releases/tag/v4.0.0-alpha.1]release page[/url]) - -- the runnable versions as a -[zip](https://github.com/codeigniter4/CodeIgniter4/releases/download/v4.0.0-alpha.1/CodeIgniter-4.0.0-alpha.1.zip) or a -[tarball](https://github.com/codeigniter4/CodeIgniter4/releases/download/v4.0.0-alpha.1/CodeIgniter-4.0.0-alpha.1.tar.gz)/ -- the developer versions of the framework (with contributor components) as -a [zip](https://github.com/codeigniter4/CodeIgniter4/archive/v4.0.0-alpha.1.zip) or a -[tarball](https://github.com/codeigniter4/CodeIgniter4/archive/v4.0.0-alpha.1.tar.gz)/ -- and finally the [epub](https://github.com/codeigniter4/CodeIgniter4/releases/download/v4.0.0-alpha.1/CodeIgniter-4.0.0-alpha.1.epub) version of the user guide for this release. - -The release has all the major features in place, but there are still gaps -and issues. See ... - -- [Bugs in the 4.0.0-alpha.1](https://github.com/codeigniter4/CodeIgniter4/issues?q=is%3Aopen+is%3Aissue+milestone%3A4.0.0-alpha) -- [Things that we definitely want to see fixed before first proper release](https://github.com/codeigniter4/CodeIgniter4/issues?q=is%3Aopen+is%3Aissue+milestone%3A4.0.0) -- [Features we would like to see in the initial proper release](), if possible, else the next update to it -- [Features that we are consciously deferring to later](https://github.com/codeigniter4/CodeIgniter4/issues?q=is%3Aopen+is%3Aissue+milestone%3A4.1.0) - -What we need now is feedback from the community ... - -- What doesn't work well (raise a post in [url=https://forum.codeigniter.com/forum-27.html]CodeIgniter 4 Development[/url]). -If you have found a bug, then by all means create a new issue on the repo. -- What you think is missing (raise a post in [url=https://forum.codeigniter.com/forum-29.html]CodeIgniter 4 Feature Requests[/url]) -We will soon start the [url=https://forum.codeigniter.com/forum-33.html]candidate new feature[/url] posts, -for those items in the feature requests forum that appear to have traction -- Problems that you are having using the release (raise a post in [url=https://forum.codeigniter.com/forum-30.html]CodeIgniter 4 Support[/url]) -Do NOT create repo issues with support questions - we are using github for bug and work package tracking - -Do NOT post support questions or feature requests in response to this thread - those -will be deleted. We are trying to make the best of the -limited resources that we have! - -Thank you, and ENJOY! \ No newline at end of file diff --git a/admin/release-revert b/admin/release-revert deleted file mode 100755 index 1c8a4eacd504..000000000000 --- a/admin/release-revert +++ /dev/null @@ -1,26 +0,0 @@ -#!/bin/bash - -## Revert local repos to pre-release state -echo -e "${BOLD}${COLOR}CodeIgniter4 release revert${NORMAL}" -echo '---------------------------' - -if [ $# -lt 2 ]; then - echo "You forgot the magic word" - exit 1 -fi -if [ $1 != 'please' ]; then - echo "What do you say?" - exit 1 -fi - -. admin/release-config - -echo -e "${BOLD}Reverting the main repository${NORMAL}" -git checkout master -git pull -f ${CI_ORG}/CodeIgniter4 master -git checkout develop -git pull -f${CI_ORG}/CodeIgniter4 develop - -#--------------------------------------------------- -# Phew! -echo -e "${BOLD}Congratulations - we have aborted liftoff${NORMAL}" diff --git a/admin/release-userguide b/admin/release-userguide deleted file mode 100755 index 6a8beb7bcbaf..000000000000 --- a/admin/release-userguide +++ /dev/null @@ -1,29 +0,0 @@ -#!/bin/bash - -## Build user guide distributable - -# Setup variables -. admin/release-config -TARGET=dist/userguide -cd $TARGET -git checkout $branch - -#--------------------------------------------------- -echo -e "${BOLD}Build the user guide distributable${NORMAL}" - -cp -rf ${CI_DIR}/user_guide_src/build/html/* docs -cp -rf ${CI_DIR}/user_guide_src/build/epub/CodeIgniter4.epub ./CodeIgniter${RELEASE}.epub - -#--------------------------------------------------- -# And finally, get ready for merging -echo -e "${BOLD}Assemble the pieces...${NORMAL}" -git add . -git commit -S -m "Release ${RELEASE}" -git checkout master -git merge $branch - -cd $CI_DIR - -#--------------------------------------------------- -# Done for now -echo -e "${BOLD}Distributable user guide ready..${NORMAL}" diff --git a/admin/workflow.md b/admin/workflow.md deleted file mode 100644 index 85e38e018ec2..000000000000 --- a/admin/workflow.md +++ /dev/null @@ -1,92 +0,0 @@ -# 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 `)... -- 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 `) -- **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. diff --git a/utils/check_permission_x.php b/utils/check_permission_x.php index 606a5f9982ca..441a875adcbe 100644 --- a/utils/check_permission_x.php +++ b/utils/check_permission_x.php @@ -32,14 +32,9 @@ function findExecutableFiles(string $dir, array $excludeDirs = []): array static $execFileList = [ '.github/scripts/deploy-userguide', '.github/scripts/secure-git-push', - 'admin/release-userguide', - 'admin/release-deploy', 'admin/apibot', 'admin/alldocs', - 'admin/release', 'admin/docbot', - 'admin/release-notes.bb', - 'admin/release-revert', 'admin/starter/builds', 'user_guide_src/add-edit-this-page', ];