Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: Check plugin compatibility before upgrading
philwareham wrote:
If anyone is unsure of what Composer is and how it works (as I kind of am), then this article does quite a good job of explaining it
Good find Phil, I’m off to read it now.
Thanks.
Offline
Re: Check plugin compatibility before upgrading
I would also recommend reading the official documentation, before and after reading that article. Start with Getting started and then move on and read every single page of the documentation, especially look at troubleshooting, basic usage and schema. The schema page is the one that actually explains you what the composer.json can contain, so that you are not blindly copy pasting what others tell you to do.
The on nettuts article doesn’t really explain the best practices and why do the things presented in the article and what they do. To be clear, it doesn’t actually even mention dependency handling or updating.
Some strong points mentioned the article that should be made clearer than presented as suggestions;
- You never commit ‘vendor’ directory your your VCS repository.
- You always commit composer.json, and composer.lock IF you are working on a project. It makes sure everyone gets the same library versions until you decide to update.
- You should never omit package version number. Instead use “flags/minumum-stability” to handle development testing.
After you have gotten Composer installed, the first command you should look into is as with any CLI application, the help:
$ composer.phar helpGives you some basic information. You may want to follow up that with running list:
$ composer.phar listWhich lists all available commands. And then by reading documentation for each specific command:
$ composer.phar help [command]I would highly suggest reading its documentation, before running any command your are not familiar with. You never want to copy paste command of some tutorial, if you do not know what it does.
Last edited by Gocom (2013-04-29 15:39:12)
Offline
Re: Check plugin compatibility before upgrading
Anyway, I’ve gotten the plugin installer to a usable state, which makes installing plugins pretty darn easy with the composer. Now extra plugins or configuration needed on your projects part really.
The installer is in alpha and current only “rah/abc_plugin” package uses it. Installing that test template plugin is super easy. You would simply create a composer.json next to your textpattern installation directory (the same directory that “textpattern” directory is in), which then includes the plugin package as a requirement:
{
"minimum-stability": "dev",
"require": {
"rah/abc_plugin" : "*@dev",
}
}The minimum compatibility flag is there to making dev packages possible. Both rah/textpattern-plugin-installer and rah/abc_plugin, do not have stable releases, yet.
After that just run Composer install command:
composer.phar installAnd should now find abc_plugin in your Plugins panel, if everything worked as it should.
The installer currently supports both manifest.json structured plugins and pre-packaged (base64) installer files. Compatible with Textpattern 4.5.0 and 4.6-dev.
Last edited by Gocom (2013-05-04 14:29:56)
Offline
Re: Check plugin compatibility before upgrading
I’ve just put out the fourth alpha iteration of the Composer installer. Three days, four alphas. The current change log looks like;
1.0.0-alpha.3 – 2013/04/30
- Fixed: Check permissions before trying to read help file.
- Fixed: Only try to read contents of actual files when constructing help documentation.
- Fixed: Works with any path structures, containing any characters in filenames, multi-byte safe.
- Added: Strips surrounding whitespace from the imported PHP source code in addition to the closing tags.
- Changed: Searches Textpattern installation from the current and the child directories, but doesn’t climb up. Otherwise it has the change of hooking to the wrong installation.
1.0.0-alpha.2 – 2013/04/29
- Fixed: Installed packages don’t incorrectly report them as modified. Didn’t calculate MD5 checksums properly.
- Changed: Does Textpattern injecting in the package type handler itself.
1.0.0-alpha.1 – 2013/04/29
- Fixed: errors.
- Added: new type “textpattern-plugin-package”.
- Added: Supports multiple plugins in one package.
I’ve updated some other plugins to use the installer. Any plugin that uses the installer can be installed using a single command:
$ composer.phar require "rah/rah_replace *@dev"
$ composer.phar require "rah/rah_terminal *@dev"Offline
Re: Check plugin compatibility before upgrading
Great. I’ve got composer installed on my mac now so I’ll give this a spin tomorrow.
Offline
Re: Check plugin compatibility before upgrading
Give a nudge if you find any errors. Oh, and when you try it out, note that the packages (plugins, the installer) do not have stable releases, so you will have to amend your minimum-stability, or Composer will yell that there is no releases available for the given package.
Now one bigger thing that should be done and worked together is to tie Textpattern itself to all that. Basically Textpattern should in a way or other be available as a composer package (project or meta etc), so that the application itself can be set as a dependency. This then allows plugins to set Textpattern versions as requirements, and you to easily check what versions the plugin is compatibile with and, if Textpattern actually used Composer, even do updating with a single command — updating plugins and Textpattern under 1 second.
To prepare for that task, and to otherwise prevent collisions or everyone taking our vendor name, I’ve reserved textpattern vendor in Composer’s central repository.
But as the Textpattern itself as a composer package goes, the unfortunate truth is, Textpattern is pretty old, and doesn’t really fit the framework and library structure itself. Plugin’s do, but like WordPress, Textpattern sticks out like a dead pixel. Ideally Textpattern would be build from separate core packages and 3rd-party frameworks (like Textile and further on expanded to others, e.g. Symfony), but that is not how Textpattern is constructed. It eventually should, it truly really should.
But we could at least have a meta package of some sort. Something to be able to set dependencies, or announce yours, even if it doesn’t really install or change Textpattern. And probably at least might be able to have a project package, or “installer” – packaged as a project package.
There are other packages that use those practices. Well, most frameworks build from packages do, if they have a “core” or their own larger “ecosystem”. For instance like Symfony has a standard package set or SilverStripe has an installer. We could have a project package containing the full repository (tags), but at least sort of stub, a meta repository.
While meta repository itself doesn’t do anything, it can be used to set dependencies and lock in project to certain version. We can also create an installer for that stub that automatically locks that package to the Textpattern version you actually have installed. The installer would basically prevent updating if Textpattern isn’t updated.
The best option would be if the whole CMS was on composer, but that is pretty much impossible. We don’t use packages, and we have that directory structure where user’s files are under our application core directory (config.php, post-updater-scripts, themes, translations), and that the public theme isn’t namespaced either. You can’t simply nuke-update that, but requires specific update scripts and rules.
Offline
Re: Check plugin compatibility before upgrading
Well I need to get back to working on Textpattern real soon – been a while, let me know if you need anything from me.
Offline
Re: Check plugin compatibility before upgrading
1.0.0-alpha.4 adds support for admin-side themes. Super-cool thing that is.
Any package using the type textpattern-admin-theme will be installed as an admin-side theme. I’ve released an example theme package, rah/abc_theme, which should give anyone interested an idea how it works and what the composer.json should look like.
In short, any theme can adopt it without any modifications by simply adding a composer.json to the theme repository (once a stable release of the installer is out, of course).
The composer package should be named after the theme. The packages name is used to find out the correct installation location and is expected to be the name of the theme. For instance if the theme is called hive and the vendor is philwareham, the package’s full name would be philwareham/hive. This would make so that the theme is installed to ./textpattern/theme/hive as Textpattern would expect. The vendor name is discarded like its with plugins (composer vendors are global, so they can not work with our prefix system, even that I was able to get “rah” myself).
Offline
Re: Check plugin compatibility before upgrading
@gocom
So I guess that pulls the theme directly from my GitHub repo yes? In that case I need to manage my repo better, as I’m just working away in the master branch at the moment and breaking stuff as I work on it. I’d have to move to working in proper branches and doing tags for releases and suchlike?
Offline
Re: Check plugin compatibility before upgrading
philwareham wrote:
So I guess that pulls the theme directly from my GitHub repo yes?
Yes, Composer uses source repositories to get the package code, which removes any need for manual packaging. Supports git, svn, hg.
In that case I need to manage my repo better, as I’m just working away in the master branch at the moment and breaking stuff as I work on it. I’d have to move to working in proper branches and doing tags for releases and suchlike?
Branching isn’t required, but tagging yes. Tags will be announce stable releases, alphas, betas and release candidates. Composer uses semver and detects the tags based on the naming conversion. This also means that releasing becomes super-simple; to release a new version and inform your users, you only need to create a tag to the repository. E.g. if you create a tag named “0.4.1” the tagged rev will be considered as the “v0.4.1”.
Branches on the other hand are not used, other than for development. Branches are considered to contain development code. Users can also use Composer to fetch non-stable dev versions, and you can use (or should) it when developing, but that is up to the user. Composer will use the version the user wants, up to the most up to date version compatible with other package and dependencies. In addition to branches, if you want to mark certain development milestones, you can use semver tags (e.g. 1.0.0.alpha.14).
Offline
Re: Check plugin compatibility before upgrading
OK thanks that makes sense. I’ve placed the composer.json file into my repo, but I need to move all the development code to another branch, put a stable version in master branch and tag it. Might be able to do that at the weekend.
Offline
Re: Check plugin compatibility before upgrading
philwareham wrote:
put a stable version in master branch
Master branch can contain the most latest development code. There is nothing wrong about committing development code to it (not even directly w/o branching), composer actual expects it to contain development code. Your end-user will not be able to fetch it by accident, but only if they explicitly want unstable development code (dictated by minimum-stability property and version constraints).
You can additionally also createaliases for branches, which help users to identify what the branch contains, and help with fetching it with version constraints.
Offline
Re: Check plugin compatibility before upgrading
Latest update to this whole Composer deal makes creating Textpattern version constraints, dependencies and requirements possible. This allows painlessly checking what packages are compatible with the installed Textpattern version. This all works by using a version lock package, a meta package — textpattern/lock.
The textpattern/lock package can be used to lock the installed Textpattern version and handle Textpattern version dependencies in packages. This package makes sure your Textpattern installation and packages are compatible and can work together.
When you start using Composer to manage Textpattern plugins and themes, the first thing you should do is to lock in your Textpattern version. This makes sure the packages you install are compatible with the Textpattern version you have. You can lock in your Textpattern version using the textpattern/lock package and Composer’s require command.
$ composer.phar require "textpattern/lock 4.5.4"Where 4.5.4 is the version of your Textpattern installation. After running the command any installed themes and plugins are checked if they are intact compatible with v4.5.4. If the requirement can not be met by any version within the constraints, then nothing is installed, and you might have to consider updating Textpattern if there is a newer version available.
The same tactic can be used to check if your existing plugins are compatible with a newer Textpattern version before updating. Just list the dependencies you have, and you will know.
$ composer.phar depends textpattern/lockYou can also try to update the locked version and see;
$ composer.phar update textpattern/lockThe version you get is the most up to date Textpattern version that is compatible with your set of plugins and themes. You can then update your Textpattern installation to that specific version.
Offline
Re: Check plugin compatibility before upgrading
The latest changes have renamed the installer package from rah/textpattern-plugin-installer to more appropriate textpattern/installer. Like the lock package, this is now under the Textpattern vendor.
Offline
Re: Check plugin compatibility before upgrading
Hi Jukka,
i tested composer on my local machine .
Got this error message : Failed to clone http://github.com/gocom/textpattern-lock.git, git was not found, check that it is installed …
And yes i am not using git but mercurial …
Offline