Laminas Maintainers Quick Reference

maintainers.md

Laminas Maintainers Quick Reference

This guide is intended for maintainers — anybody with commit access to one or more Laminas repositories. It's a quick version of the original maintainers guide without the noise and extra tools to merge PR's and create releases faster.

Preparations:

• Global install keep-a-changelog $ composer global require phly/keep-a-changelog
• Install github/hub $ curl -fsSL https://github.com/github/hub/raw/master/script/get | bash -s 2.14.2

Add upstream

$ git remote add upstream git@github.com:<original-namespace>/<projectname>.git

Keep your local clone synced!!!

# Shortcut: git sync-upstream <master|develop>

$ git checkout master && git fetch upstream master && git rebase upstream/master
$ git push origin master

$ git checkout develop && git fetch upstream develop && git rebase upstream/develop
$ git push origin develop

Merge and Release

• Merge hotfix
• Merge feature
• Maintenance release
• Feature release

merge-feature.md

Merge feature

Prepare a feature

$ git checkout -b feature/123 develop

Pull in the changeset

$ hub merge https://github.com/<original-namespace>/<projectname>/pull/123

Create a Changelog

$ keep-a-changelog entry:added --pr 123 "adds documentation."
$ keep-a-changelog entry:changed --pr 123 "changes something."
$ keep-a-changelog entry:deprecated --pr 123 "deprecated something to be removed in the next major release."
$ keep-a-changelog entry:removed --pr 123 "removes something."

Commit changelog

$ git commit -sam "docs: add changelog for #123"

Merge feature to develop

$ git checkout develop
$ PR="123"; git merge --no-ff "feature/$PR" -m "chore: merge branch 'hotfix/$PR'" -m "Close #$PR"

Push changes

$ git push upstream develop:develop

Delete the merge branch you created

$ git branch -d feature/123

Tag the PR in GitHub for the next minor or major release milestone (e.g., "2.1.0"). This allows users to see when a pull request will release and/or was released.

merge-hotfix.md

Merge hotfix

Replace xx with with the PR number

Prepare a hotfix

$ git checkout -b hotfix/123 master

Pull in the changeset

$ hub merge https://github.com/<original-namespace>/<projectname>/pull/123

Create a Changelog

$ keep-a-changelog entry:fixed --pr 123 "fixes something to be Better."

Commit changelog

$ git commit -sam "docs: add changelog for #123"

Merge hotfix to master

$ git checkout master
$ PR="123"; git merge --no-ff "hotfix/$PR" -m "chore: merge branch 'hotfix/$PR'" -m "Close #$PR"

Merge hotfix to develop

$ git checkout develop
$ PR="123"; git merge --no-ff "hotfix/$PR" -m "chore: merge branch 'hotfix/$PR'" -m "Forward port #$PR"

Push changes

$ git push upstream master:master && git push upstream develop:develop

Delete the merge branch you created

$ git branch -d hotfix/123

Tag the PR in GitHub for the next maintenance milestone (e.g. "2.0.4"). This allows users to see when a pull request will release and/or was released.

release-feature.md

Feature release

Replace x.x.x with a semver version like 3.3.0

Merge the develop branch to master:

$ git checkout master
$ git merge develop

Create a branch for the new version.

$ git checkout -b release/x.x.x master

Quality Assurance checks

$ composer check
$ ...

• Check that there is not an empty stub or unreleased maintenance version in the CHANGELOG.md. For empty stubs, just remove the full entry; for an unreleased maintenance version, merge the entries with those for the new minor or major release.
• Update the branch-alias section of the composer.json to bump the dev-master and dev-develop releases. As an example, if you are preparing a new 3.3.0 release, dev-master would now read 3.3.x-dev and dev-develop would read 3.4.x-dev. For a new major version 4.0.0, these would become 4.0.x-dev and 4.1.x-dev, respectively.

Update the release date and commit the changes.

$ keep-a-changelog version:ready
$ git commit -sam "chore: prepare release x.x.x"

Merge the release branch into master and tag the release.

$ git checkout master
$ git merge --no-ff release/x.x.x
$ git push upstream master:master
$ keep-a-changelog version:tag x.x.x
$ keep-a-changelog version:release --remote upstream x.x.x

Merge to the develop branch.

$ git checkout develop
$ git merge --no-ff release/x.x.x

Create a CHANGELOG stub for the next minor version.

$ git checkout -b version/bump master
$ keep-a-changelog bump:bugfix
$ git commit -sam "chore: bumped version to x.x.x"
$ git checkout master && git merge --no-ff -m "docs: bumped version" version/bump
$ git checkout develop && git merge --no-ff -m "docs: bumped master version" version/bump
$ git branch -d version/bump

Create a CHANGELOG stub for the next develop version.

$ git checkout -b version/bump master
$ keep-a-changelog bump:minor
$ git commit -sam "chore: bumped version to x.x.x"
$ git checkout develop && git merge --no-ff -m "docs: bumped develop version" version/bump
$ git branch -d version/bump

Push the two branches and the new tag:

$ git push upstream master:master && git push upstream develop:develop

Finally, remove your temporary branches:

$ git branch -d version/bump release/x.x.x

release-maintenance.md

Maintenance release

Replace x.x.x with a semver version like 3.2.1

Create a branch for the new version.

$ git checkout -b release/x.x.x master

Quality Assurance checks

$ composer check
$ ...

Update the release date and commit the changes.

$ keep-a-changelog version:ready
$ git commit -sam "chore: prepare release x.x.x"

Merge the release branch into master and tag the release.

$ git checkout master
$ git merge --no-ff release/x.x.x
$ git push upstream master:master
$ keep-a-changelog version:tag x.x.x
$ keep-a-changelog version:release --remote upstream x.x.x

Merge to the develop branch, as you would for a bugfix:

$ git checkout develop
$ git merge --no-ff release/x.x.x

Next, you need to create a CHANGELOG stub for the next maintenance version.

$ git checkout -b version/bump master
$ keep-a-changelog bump:bugfix
$ git commit -sam "chore: bumped version to x.x.x"
$ git checkout master && git merge --no-ff -m "docs: bumped version" version/bump
$ git checkout develop && git merge --no-ff -m "docs: bumped master version" version/bump
$ git branch -d version/bump

Conflicts

Be aware that this last merge to the develop branch will generally result in a conflict, as, if you are doing things correctly, you'll have an entry for the next minor or major release in the develop branch, and you're now merging in a new empty changelog entry for a maintenance release.

$ git add .
$ git commit

Push the two branches:

$ git push upstream master:master && git push upstream develop:develop

Finally, remove your temporary branches:

$ git branch -d version/bump release/x.x.x