Publishing and distribution
Publishing themes and extensions: repositories, packages, releases, versions and licenses.
40 pages
- Distributing a theme: start here The map for publishing a theme - GitHub repository, version numbers and permanent tags, releases and changelogs, Packagist, licensing choices, screenshots and demo sites, and the community sites share.exponential.earth…
- Checklist: before you publish The final checklist before a theme release goes public - repository, licenses, version and tag, release notes, Packagist, screenshots, listings, support and security - each item linked to the page that explains it.
- Choosing where to publish The places a theme for Exponential can be published - a Git host (GitHub), Packagist for Composer, projects.exponential.earth, announcements on share.exponential.earth, and your own website - what each gives you and in…
- Creating the GitHub repository Create a public GitHub repository for a theme with the gh command line or in the browser, connect your local repository, and set the description, website, issues and license so GitHub shows them.
- Repository name, description and topics Choose a repository name, a one-line description and GitHub topics that let people find a theme, with the choices the published Exponential themes made.
- A README that explains and sells Turn a theme's README into the page that convinces - the first screen, a screenshot, proof of quality (accessibility, CSP, dark mode), honest requirements, a two-minute install and clear support - without claims you…
- The first push and the default branch Push a theme for the first time with main as its default branch, protect main from force pushes, and decide how work branches and pull requests flow into it.
- Choosing a version number How to pick the next version number of a theme - from what is already published, raising only the last position for normal releases, and moving a higher position only as a deliberate decision about what the release…
- After .9 comes .10: only the last position counts A version at .9 goes to .10, not to the next higher position - why that is safe for Composer, Packagist and GitHub, and why positions above the last move only by decision.
- Sorting tags correctly List the tags of a theme in version order, not name order - git tag --sort=version:refname, sort -V and git describe - with the mistake a plain sort makes and how to fix release scripts.
- Checking what is already published Before choosing a version number, list the tags on the remote, the GitHub releases and the versions Packagist knows, because each can know something the others do not.
- Bumping the version before the tag The release commit - write the new number into ezinfo.php, extension.xml and the other version fields, check them, commit, and only then tag that commit - so the tag carries the right number forever.
- Annotated tags Tag releases with annotated tags (git tag -a) that carry a message, an author and a date; how to write the message, check the tag before pushing, and push only that tag.
- A pushed tag is permanent Why a tag and the release built from it can never be deleted, moved or re-cut once pushed - Packagist caches what it read, users keep what they installed - and the rules that follow for every theme author.
- GitHub releases Create a GitHub release for a pushed tag with gh release create - title, notes from the changelog, latest flag - check it, and know what a release adds to a tag.
- Writing release notes Write release notes users can act on - a headline, what changed for them, what they must do after upgrading, credits, and an honest note about any earlier mistake - with a real example from a published theme.
- When a release goes wrong What to do when a published theme release is broken - leave it in place, fix forward with the next version, say plainly what was wrong, and tell users which version to move to.
- Changelog entries: Added, Updated, Removed, Renamed, Fixed Write changelog entries and commit messages with one of five prefixes so a changelog can be assembled from history - what each prefix means, good and bad examples, and one change per entry.
- Keeping a CHANGELOG.md Maintain a theme's CHANGELOG.md release by release - collect entries from the git log since the last tag, sort them by prefix, add the heading in the release commit, and keep the file and the GitHub releases consistent.
- Submitting a theme to Packagist Publish a theme as a Composer package on Packagist - prerequisites, the Submit page, checking the package page, and testing composer require from a clean installation.
Documentation license
This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.
Exponential Copyright © 1998-2026 Exponential Foundation and 7x
