Package managers integration

[Piotrek Koszuliński]

There are plenty package managers out there, but let's focus first on two of them:

• Bower (JS)
• Composer (PHP)

Steps:

• Make all necessary steps to make CKEditor easily installable with those PMes. The package that should be installed by default is stable/standard (which equals master) from ​https://github.com/ckeditor/ckeditor-releases. If PM allows to have alternative, we can also make other (basic and full) presets installable.
• The above will perhaps require: #10882. We already tagged CKEditor 4.3 as 4.3.0. To close #10882 we should also add missing tags for historic releases (4.3.0-beta, 4.2.0, 4.1.0, 4.1.0-rc, etc). Additionally, to conform ckeditor-releases with SemVer we may need to create tags without "/standard|basic|full" suffix - e.g. 4.3.0 === 4.3.0/standard.
• Readmes in ckeditor-dev and ckeditor-releases have to be updated. The ckeditor-dev's mentions the 4.0 tag and ckeditor-releases has to contain information about installing CKEditor with Bower and Composer.
• Installing through package managers has to be mentioned in our guides. Please contact Ania to choose the best place.
• The PM integration should be mentioned in release blog post.

---

Final decisions for this ticket. We agreed that we can start with the really basic solution, so only one available preset (standard). Having 4 different presets would require having 4 different repositories (a lot of work to do) or otherwise we would be able to support only Composer and not Bower, so it's also making situation more complicated.

[Marek Lewandowski]

Ok I've took a look into Composer and Bower.

Composer:

a) We are not able to publish our ckeditor-releases to work with composer. That's because it requires format: X.Y.Z or vX.Y.Z optionally followed by one of -dev, -patch, -alpha, -beta, -RC. Any other suffix will be recognized as invalid, so our -full, -standard suffixes would break it.

What we need to do to bring Composer support?

1. resolve issue with tag naming
2. create composer.json file in ckeditor-releases repository ( we don't need to do it in ckeditor-dev though )
3. ​fill form in order to register ckeditor in packagist

b) Alternative approach: we can handle it at our new server.

All we need to do is to generate packages.json file, and make a script which would re-generate it's content upon each release (as it would be bad idea to do it manually).

As a result CKEditor would be accessible with phrases like: "cksource/ckeditor", "cksource/ckeditor-full", "cksource/ckeditor-basic", "cksource/ckeditor-standard".

End-user could use then config like:

{
	"require": {
		"cksource/ckeditor-full": "4.*"
	}
}

We dont even need to host zip archives, since we may hotlink github archives.

---

Bower:

Currently we are able only to fetch ckeditor only by typing exact tag name, like following:

Bower install ckeditor#4.3.0/full

Any other method will not fetch CKEditor. In order to be able work with Bower we must change tag format to meet ​semver. Then we need to register it with bower register command.

I'll try to do some extra research if the Bower allows us to specify explicitly in the same fashion as Composer does in point b.

[Marek Lewandowski]

Unfortunately Bower does not give us so much options as Composer does.

[Marek Lewandowski]

Ok, I've created a script which will generate automatically json file for Composer, based on our tags in ckeditor-releases repository. Here is a sample output saved as packages.json.

To play around by yourself:

1. download ​Composer
2. download attached packages.json file
3. place it somewhere, where it will be accessible using http:// protocol, lets assume that its address will be http://localhost/composer/packages.json
4. create a new directory at some other directory (there you will download CKEditor via Composer)
5. create composer.json file with following content:

   {
     "repositories": [
       {
         "type": "composer",
         "url": "http://localhost/composer/"
       }
     ],
     "require": {
       "cksource/ckeditor": "<4.1.3,>=4.1"
     }
   }
   

6. go to that directory with your command prompt and type

   composer update
   

As a resoult you should have following output

Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing cksource/ckeditor (4.1.2)
    Downloading: 100%

If you will take closer look to require property in composer.json, you can use also cksource/ckeditor-full and others there. In case cksource/ckeditor it will point to standard preset.

Note: for simplicity sake, currently json hotlinks to github, we may use our own cdn there.

[Marek Lewandowski]

packages.json

[Marek Lewandowski]

Mentioned script added to tools repository in branch t/11279.

[Marek Lewandowski]

Ok so we decided to create tags in following format: x.y.z

which will contain CKEditor standard-all build.

TODO:

• create x.y.z format branches
• update README ( section about tags )
• write docs about downloading CKEditor with Composer / Bower
• update ck-release script
• optionally we may create bower.json
• create composer.json ​(more details) like:

  {
  	"name": "cksource/ckeditor",
  	"description": "Javascript WYSIWYG editor.",
  	"keywords": [ "wysiwyg" ],
  	"homepage": "http://www.ckeditor.com",
  	"support": {
  		"issues": "http://dev.ckeditor.com",
  		"forum": "http://ckeditor.com/forums",
  		"source": "http://github.com/ckeditor/ckeditor-dev"
  	}
  }
  

[Marek Lewandowski]

While testing it turned out that git does not allow us to create tags in x.y.z in releases repo due to our current tag convention. The reason is that it treat tags similarly to directory structure, so once we've created tags like 4.3.2/basic we couldn't create 4.3.2 tag, because it's already acting like a "directory". Once again we had to change our conception.

New conception:

Since 4.3.3 we'll

• switch tagging pattern from x.y.z/preset to x.y.z-preset
• introduce x.y.z tag, without any suffix

Table illustrates which pressets distribution

tag name schema	build preset
x.y.z	standard-all
x.y.z-basic	basic
x.y.z-standard	standard
x.y.z-full	full

Remarks:

• z is mandatory

Potential drawbacks:

Issue with tagging RCs

We will have semantical issue creating a RC, maybe lets spend extra minute on thinkin such case.

According to ​Semver2, RCs names should be created as follows:

4.3.0-rc.1

EVENTUALLY what we can do is create tags like:

4.3.0.rc.1
4.3.0.rc.1.basic
4.3.0.rc.1.standard
4.3.0.rc.1.full

• but it's kinda of heavy abuse

Other than that i don't see any issues now :)

[Piotrek Koszuliński]

Replying to comment:9. You're right Marek that 4.3.0-beta-full will be confusing. We'd completely mix version with preset, so let's try to use less confusing slashes. The association it has with directories is very good. We just haven't been lucky with the limitation of git you mentioned.

New proposal

tag name schema	build preset
x.y.z	standard-all
basic/x.y.z	basic
standard/x.y.z	standard
full/x.y.z	full

Remarks:

• The master, stable and latest points to latest x.y.z (standard-all build) instead of standard build.
• Tags for standard-all preset follows SemVer spec. This applies also to the part after slash in other presets' tags.
• Presets are clearly separated from versions - there will be clear situation in alphabetically sorted list of tags. First semantic ones (4.4.0, 4.4.1, 4.4.2, ...), then ones for basic preset (basic/4.4.0, basic/4.4.1, ...), then full and then standard.

[Marek Lewandowski]

Ok I've confirmed that our approach is fine with composer (and bower too).

Adding composer.json file

From now on we will need to place composer.json file in main directory of releases. Struct which i suggest is following:

{
	"name": "ckeditor/ckeditor",
	"description": "Javascript WYSIWYG editor.",
	"type": "library",
	"homepage": "http://www.ckeditor.com",
	"license": [ "GPL-2.0+", "LGPL-2.1+", "MPL-1.1+" ],
	"support": {
		"issues": "http://dev.ckeditor.com",
		"forum": "http://ckeditor.com/forums",
		"source": "http://github.com/ckeditor/ckeditor-dev"
	}
}

Reminder: while creating file please double check, and ensure that there is no BOM**

As of name I suggest using ckeditor/ckeditor rather than cksource/ckeditor, see ​Packagist Guides (Naming your package section) for more info.

As of licenses, I'd like WW or some1 to review above info. There is one issue with MPL-1.1+ (Mozilla Public License Version 1.1 or later) - is not listed in ​http://spdx.org/licenses. ​License property spec does not state that it's limited to SPDX registry. At the same time Composer highly recommends filling this field, make sense especially for such project as ours.

For more informations which may be included in this fille head to ​its specification. I suggest adding keywords.

What about bower.json?

AFAICS it handles it correctly without bower.json file, so there is no need to add it - the only thing which we need to do is to change tag label pattern.

Docs

I can be a volunteer for writing documentation for downloading CKEditor using Composer/Bower.

[Piotrek Koszuliński]

Regarding composer.json file - we talked that our release script should add it, but since this file does not contain any changing variable like version, you can add it in a commit to ckeditor-releases and update release script so it doesn't remove it (similarly to README.md).

And one crucially important thing. JavaScript, not Javascript ;>>>.

Additionally:

• ckeditor/ckeditor name is ok - the main repo is under ckeditor/ckeditor-dev, because cksource/ckeditor-dev is our contribution to official CKEditor.
• Maybe we should point from support.wiki to ​http://docs.ckeditor.com.
• From where Bower gets this information? It's not a problem to have bower.json too, so we can add it if it helps for something.
• Please coordinate docs, keywords and description with Ania.

[Anna Tomanek]

My proposal for the composer.json file: ​https://gist.github.com/AnnaTomanek/76bedfb825daaafa9ab2

{
	"name": "ckeditor/ckeditor",
	"description": "JavaScript WYSIWYG web text editor.",
	"type": "library",
	"keywords": [ "ckeditor", "fckeditor", "editor", "wysiwyg", "html", "richtext", "text", "javascript" ],
	"homepage": "http://ckeditor.com",
	"license": [ "GPL-2.0+", "LGPL-2.1+", "MPL-1.1+" ],
	"authors": {
		"name": "CKSource - Frederico Knabben",
		"homepage": "http://cksource.com"
	},
	"support": {
		"issues": "http://dev.ckeditor.com",
		"forum": "http://ckeditor.com/forums",
		"wiki": "http://docs.ckeditor.com",
		"source": "http://github.com/ckeditor/ckeditor-dev"
	}
}

I added the keywords, author, and wiki fields.

[Marek Lewandowski]

Composer / Bower support introdcued in 4.3.3, that closes this issue.

There is also an article in docs, describing how to download ​CKEditor with package managers.