Best practices for TYPO3 extension development with Git (or other VCS)

gistfile1.rst

Versioning scheme

Stick to Semantic Versioning.

Releases

The official way of releasing TYPO3 extensions is to the TER, extensions existing solely as Git repositories are NOT properly made available to the community.

Compatibility

• master branch should always target upcoming version of TYPO3
• You should try to keep backward compatibility as for TYPO3 CMS, that is, deprecate API and remove 2 versions (major/minor) later

The branch structure within your project may vary but basically, you should have a branch containing code base compatible or aiming at being compatible with the upcoming version of TYPO3. E.g., during the development of TYPO3 7 LTS (at time of writing version 7.3.0 is about to be released), one of your branches should target 7.99.99.

Rationale: even if you cannot afford investing time (and thus money) for a version of TYPO3 you still don't support (your clients are using TYPO3 6.2 LTS and not any 7.x snapshot version), having a branch eventually targeting 7.x (read: the upcoming version at time of reading) allows users to suggest changes and patches to make it compatible.

When your master branch (and no other branch exists for "dev") is stuck to 6.2 compatibility, you give the wrong signal that your extension is likely to not being actively maintained and developped anymore and that using it is actually a risk because it may prevent the user to upgrade the website when 7 LTS is out.

Repository

Public extensions (released to TER) should be developped in a public repository as well. This is obvious if you think about getting bug fixes from your users.

Contribution

• You should ask for contribution in the form of either pull requests (GitHub) or patch sets sent to Gerrit (TYPO3 Core and basically every 3rd-party extension hosted on git.typo3.org)
• Contributions should be related to tickets in a bug/feature tracker
• Documentation should be written in Sphinx (read more)

How-to properly release

1. Ensure every local modification is committed
2. Raise version (in ext_emconf.php and Documentation, composer, ...) and commit
3. Publish the extension to TER (with a meaningful upload comment, ideally together with link to release notes)
4. Tag the version (git tag 1.2.3 && git push --tags)
5. Raise version to next target (normally patchset release 1.2.4-dev) and commit

Can you clarify the TER Release? I was thinking that the Upload to TER was manipulating the version info in ext_emconf.php. Or am I wrong?

Kay Strobach has mentioned this: https://github.com/NamelessCoder/typo3-repository-gizzle

"This project allows any GitHub-hosted repository containing a TYPO3 CMS extension to be released to the official TYPO3 Extension Repository (hereafter referred to as TER) by adding a very simple GitHub web hook."

Oh the subject of Gizzle - I was told by the server team a while ago that they'd like to implement a self-hosted version of exactly the project Kay mentioned, which I assume would then be integrated with TER so that adding a GitHub repository URL and some sort of token would enable automatic TER releases from GitHub.

The only thing that would happen to the release process described above, is the 3rd step which is no longer necessary. It would simply be grabbed from the tagged Git release after the 4th step. Any non-tag push is just ignored.

Thanks for the Gist! Two little typos:
sed 's/structure structure/structure/'
sed 's/Contribution should/Contributions should/'

@dkd-dobberkau: The 4.5 EM did version number manipulation, in 6.2 EM you better use one of the CLI tools and set the proper attributes yourself: https://github.com/etobi/Typo3ExtensionUtils

@dkd-dobberkau: in fact, the TER itself (or more precisely the SOAP webservice) takes the version that is given as parameter and just checks that it does not exist, it's up to "you" to give a bigger version number or a smaller if you want to fix an older branch, TER really does not care at all!

In addition, 4.5 EM was updating the "checksums" info in ext_emconf.php but as EM nowadays has no way to see if extension files have been locally modified (according to their "official" checksum), best is to remove/empty this info once for all now.

@marble: thanks, fixed!