Amazing! You’ve made a great decision to OpenSource contribute to the TER TYPO3 Extensions, I appreciate it! Are you looking for help to publish the TER TYPO3 extension? In this article, You will find a step-by-step guide to release manuals or automize your extension to TER.
TYPO3 Extensions Repository (aks TER) is a centralized place where many TYPO3 agencies and developers develop and publish their TER TYPO3 extensions - As give back to OpenSource. For productive work of the TYPO3 developer, publishing, and deployment of extension to TER should be easy and convenient. That’s why I’m writing this article to help you - to save your time. You just focus on the development of your TER TYPO3 extensions, and let’s automate the publish :)
Our App Store is Called TER - and It's Free!
-TYPO3 GmbH
Create TYPO3.org Account
To publish your TYPO3 extensions at TER, You will need to create an account at TYPO3.org.
Step 1. Land to My.TYPO3.org - A central for all TYPO3 sites https://my.typo3.org/register
Register TYPO3 Extension Key
Before you start to develop your TYPO3 extension, It’s essential to check, register and validate your TYPO3 extension key.
Step 1. Click on “My Extensions” from Main-menu https://extensions.typo3.org/
Initiate Git Public Repository
90% of TYPO3 developers use Git repositories to develop and well-maintained their TYPO3 extensions for public TER as well as private projects too.
What Are Recommended Git Tools?
- Github.com
- Gitlab.com
- Bitbucket.com
Why Git repositories for TER Extension?
- Easily maintain code repositories
- Automatically publish TYPO3 extension to TER
- The community can contribute code to your TYPO3 extension
- Code review with Lints
- Allow people to use the master repository
- And, so on!
Prepare TYPO3 Documentation
Well, it’s not the technical part, but very important for the people who want to use your TYPO3 extensions.
What should we include in TYPO3 documentation?
- Introduction
- Screenshots
- Installation & Configuration
- Users Guide
- Integrator Guide
- Developer Guide (if any)
- Support
- FAQ
Option 1. Official Docs.TYPO3.org
Read the step-by-step guide at How to Document an Extension.
Option 2. Your External Documentation
Many developers just want to make simple-own documentation without follow-up RST format of docs.typo3.org; You can simply create documentation in the below ways.
Using README.md at your Git repository
- Write a blog about the extension.
- Use Wiki at your Git repository.
- Etc.
For this case, You will need to provide a documentation URL at your extension as below
Issues Management
It’s a good idea to provide a bug-tracker or issues management system to the TYPO3 community, so if you find something wrong at your TYPO3 extension, then they can report.
Simply you can use your Git repository’s “Issues Management”, And make sure to provide “Link to issue tracker” at your extension as below.
How to Publish Your TYPO3 Extension to TER?
1. Manually Publish at Extensions.TYPO3.org
Step 1. Go to “My Extensions” at https://extensions.typo3.org
Step 2. Click on “Upload” button at your registered TYPO3 extension
Step 3. Write a description, Upload yourextesion_1.0.0.zip, and Click on the “Upload extension” button.
2. Github: NamelessCoder’s Automatic Release
NamelessCoder.net mini-site is a service that lets you release a GitHub repository containing a TYPO3 extension directly from GitHub to the TYPO3 Extension Repository (TER). New releases are made every time a new version is tagged on GitHub. Free to use.
Requirements
- A public GitHub repository containing your TYPO3 extension.
Installation
- Go to Github Repository > Settings
- Locate the "Webhooks & Services" tab
- Click "Add webhook."
- Enter in "URL": username:password@release.namelesscoder.net/my_extension.
- my_extension is the lowercase underscored extension key to release.
- Username: password is your credentials with permission to upload the extension.
- Enter in "Secret": typo3rocks
- Leave the "Events" selection as it is - this service only requires the push event.
Automatically Release Extension from Github to TER
create/push tag
git tag 1.2.3
git push origin 1.2.3
3. Gitlab: CI to TER
If you are using Gitlab, then you can simply write a deployment script into GitLab-ci.yml to automatically release the TYPO3 extension from Gitlab to TER.
# gitlab-ci.yaml
cache:
key: "$CI_COMMIT_REF_NAME-$CI_JOB_STAGE"
paths:
- .composer/
before_script:
- apk add git --update
stages:
- upload
# TER Upload when tagging in the master branch
# The variables T3O_USERNAME and T3O_PASSWORD should be set in GitLab
ter-upload:
image: php:7-alpine
stage: upload
only:
- tags
before_script:
- curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
- export COMPOSER_CACHE_DIR=.composer
script:
- composer install
- composer require namelesscoder/typo3-repository-client
- export TYPO3_PATH_WEB="$PWD/.Build/Web"
- >
if [ -n "$CI_COMMIT_TAG" ] && [ -n "$T3O_USERNAME" ] && [ -n "$T3O_PASSWORD" ]; then
echo -e "Preparing upload of release ${CI_COMMIT_TAG} to TER\n"
# Cleanup before we upload
git reset --hard HEAD && git clean -fx
# Upload
TAG_MESSAGE=`git tag -n10 -l $CI_COMMIT_TAG | sed 's/^[0-9.]*[ ]*//g'`
echo "Uploading release ${CI_COMMIT_TAG} to TER"
.Build/bin/upload . "$T3O_USERNAME" "$T3O_PASSWORD" "$TAG_MESSAGE"
fi;
4. Github: TYPO3 Extension Utils (T3XUtils)
Important notes from author: Thanks for mentioning, But I do NOT recommend using T3XUtils anymore. It is not maintained for a while now. :-) https://twitter.com/etobi/status/1296809514839285761
Using Typo3ExtensionUtils tool, You can quickly deploy TYPO3 extension to TER using t3xutils.phar CLI. This is a collection of CLI utilities for the TYPO3 CMS Extension. The goal is to be able to do common tasks while developing extensions from the CLI. All tools work without a fully functional TYPO3 installation. Actually the TYPO3 CMS core isn't needed at all for these utilities.
Installation
git clone https://github.com/etobi/Typo3ExtensionUtils.git
cd Typo3ExtensionUtils/bin/
chmod +x t3xutils.phar
./t3xutils.phar help
Upload Extension to TER
./t3xutils.phar upload <typo3.org-username> <typo3.org-password> <extensionKey> "<uploadComment>" <pathToExtension>
./t3xutils.phar upload eTobi.de 'mySecretPassword' foobar "Minor Bugfixes and cleanup" /var/www/foobar/typo3conf/ext/foobar/
5. Github: Travis-CI to TER
Helmut - The TYPO3 man wrote an article to release TYPO3 Extension with Travis-CI to TER automatically.
# .travis.yml
language: php
# Do not build feature branches
branches:
only:
- latest
- develop
- /^v?([0-9]+\.){1,2}(x|[0-9]+)-?[a-z]*[1-9]*$/
# This is executed for all stages
before_install:
- if php -i | grep -v TRAVIS_CMD | grep -q xdebug; then phpenv config-rm xdebug.ini; fi
# Configure build stages (with build matrix above, the test stage is implicitly defined)
jobs:
allow_failures:
- env: TYPO3_VERSION="dev-master"
include:
- stage: update extension repo
if: type = push
php: 7.2
before_install: skip
install: skip
before_script:
- mkdir -p ~/.ssh
- openssl aes-256-cbc -K $encrypted_85bf36ae99bb_key -iv $encrypted_85bf36ae99bb_iv -in Resources/Private/deploy_rsa.enc -out ~/.ssh/id_rsa -d
- echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config
- chmod 600 ~/.ssh/id_rsa
- git clone git@github.com:TYPO3-Console/Extension.git ../extension -b template
- cd ../extension && git checkout origin/$TRAVIS_BRANCH || true && cd -
- composer extension-release
- cd ../extension
- git checkout README.md
- git add .
script:
- |
if [ -n "$TRAVIS_TAG" ]; then
git commit -m "Release extension version $TRAVIS_TAG" --author "Name <email>"
git tag $TRAVIS_TAG
git push --tags
else
git commit -m "Update extension based on commit $TRAVIS_COMMIT" --author "Name <email>"
git push origin HEAD:$TRAVIS_BRANCH
fi;
- stage: ship to TER
if: tag IS present
php: 7.2
install: skip
before_script: skip
script:
- |
if [[ "$TRAVIS_TAG" =~ ^v?([0-9]+\.)([0-9]+\.)([0-9]+)$ ]] && [ -n "$TYPO3_ORG_USERNAME" ] && [ -n "$TYPO3_ORG_PASSWORD" ]; then
echo -e "Preparing upload of release ${TRAVIS_TAG} to TER\n";
# Install ter client
composer global require helhum/ter-client
# Build extension files
composer extension-release
# Upload
TAG_MESSAGE=`git tag -n10 -l $TRAVIS_TAG | sed 's/^[v]*[0-9.]*[ ]*//g'`
echo "Uploading release ${TRAVIS_TAG} to TER"
$HOME/.composer/vendor/bin/ter-client upload typo3_console ../extension -u "$TYPO3_ORG_USERNAME" -p "$TYPO3_ORG_PASSWORD" -m "$TAG_MESSAGE"
fi;
6. TYPO3 Repository Client API/CLI
TYPO3 Extension Repository (TER) client library and CLI commands
Usage
Each command which can be executed has a corresponding class, for example, NamelessCoder\TYPO3RepositoryClient\Uploader and a CLI script which acts as a wrapper for said class. The parameters which should be passed to each CLI script must be the same arguments and in the same order as required by the class' method.
Uploader
// As component:
$uploader = new \NamelessCoder\TYPO3RepositoryClient\Uploader();
$uploader->upload('/path/to/extension', 'myusername', 'mypassword', 'An optional comment');
// And as CLI command:
./bin/upload /path/to/extension myusername mypassword "An optional comment"
7. TER Client
TYPO3 Extension Repository (TER) client library and Symfony Console command. This has been built on the shoulders of namelesscoder/typo3-repository-client.
Installation
Use composer to install the TER Client: composer require helhum/ter-client
Usage
Each command which can be executed has a corresponding class, for example, Helhum\TerClient\Uploader and a CLI script which acts as a wrapper for said class. The parameters which should be passed to each CLI script must be the same arguments and in the same order as required by the class' method.
Uploader
// As component:
$uploadPacker = new ExtensionUploadPacker();
$connection = Connection::create($wsdUrl);
$result = $connection->upload(
new UsernamePasswordCredentials($username, $password),
$uploadPacker->pack($extensionKey, $directory, $comment)
);
// And as CLI command:
ter-client upload ext_key /path/to/extension -u myusername -p mypassword -m "Upload Comment"
8. TER TYPO3 Extensions WSDL Services
CI environments (like Jenkins or GitLab CI) can execute these commands, it ought not to be that difficult to publish an extension automatically.
Interestingly, there lies a public SOAP interface for the TYPO3 Extension Repository. The entirety of the as of now referenced solutions utilize this API.
You can discover it under the URL https://typo3.org/wsdl/tx_ter_wsdl.php.
If you wish to dig up, you can utilize the product SmartUI by SmartBear (Link: https://www.soapui.org/).
Tips & Tricks for TER TYPO3 Extensions
Semantic Versioning 2.0.0
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backward-compatible manner
- PATCH version when you make backward-compatible bug fixes
- Read more at semver.org
Support Composer
As a modern TYPO3 developer, You should provide composer support.
Now it is time to configure composer, Packagist.org provides straightforward configuration to connect between your Git repository and Composer. Of course, Packagist also supports other Git platforms like Gitlab ;)
Submit Git repo at Packagist
Step 1: Go to https://packagist.org/.
Step 2: To sign-up, you may use either https://packagist.org/register/ or use “Login with Github” at https://packagist.org/login/
Step 3: Now, Let’s submit our package/extension, Click on “Submit” https://packagist.org/packages/submit
Step 4: Enter your Github repository URL, and click on the “Check” button. Verify it once and then submit your package.
If you are getting some errors, then cross-verify your composer.json at your Git repository.
Step 5: Now you will be redirected to your package landing page eg., https://packagist.org/packages/nitsan/ns-news-comments Here you can see, all the information is grabbing from your Github’s composer.json file.
How Packagist and Git will communicate?
Whenever you’ll make any change or release a new version at Github, how will they communicate to take the latest code to the composer? Perform the following steps.
Get API Token from Packagist
Step 1: Go to your profile https://packagist.org/profile/
Step 2: Click on “Show Token API” button
Step 3: Go to your Github repository > Settings > Webhooks > Click on Add webhook button
Step 4: Fill-up details
- Payload URL: https://packagist.org/apidoc
- Content-type: application/JSON
- Secret: Add your API token key from Packagist
Enable Composer Command
If you are all set with the composer, then make sure to “Enable Composer” for your TYPO3 extension at TER as below.
Hurray!
Your TYPO3 Extension detail page got a composer command.
// Support TYPO3 Composer Command
composer req nitsan/ns_backup
Wrap-up!
Thanks for reading the article!
I hope you learn and enjoy publishing TER TYPO3 Extensions. Let's quickly recap.
- Setup your account at TYPO3.org, And register your extension key at TER.
- Prepare your local environment with your favorite Git tool.
- As an add-on, Do your best to make better documentation for users and developers.
- Choose your convenient way to publish your TER TYPO3 extension; My favorite is NamelessCoder's service which is just plug-n-play.
What’s your favorite way to publish the TER TYPO3 extension? Are you facing any issues to set up one of the above methods to launch your TER TYPO3 extension? I’ll be happy to answer any questions in the comment box below.
Have a Happy TYPO3 Contribution :)
Post a Comment
- Really nice article! Exactly what i needed, thank you.
- Thanks Sanjay. The TYPO3 extension upload blog is super awesome and I appreciate you taking the time to detail all this out so well. I bookmarked this page just in case I really need it one day.
Sanjay Chauhan
CTO at T3Planet & NITSANSanjay Chauhan, Co-Founder of NITSAN (Award winning TYPO3 agency) and Pioneer of T3Planet (first-ever TYPO3 Store).
A true TYPO3 fanatic since 2010. I bring strong TYPO3 experience in building customer-business…
More From Author