Rules for sumitting to Packagist

[Anselm Christophersen]

I'm in the process of submitting the one theme I have that I think is worth to submit to packagist, but have a little question: I've just started using Composer, and am still having a little trouble locating modules worth checking out, also as it seems people are using different conventions when publishing modules on packagist.

You've probably discussed this internally at Silverstripe, and maybe I've just missed it, but my question is the following. Should module maintainers publish silverstripe packages under the Silverstripe name as this one:

https://packagist.org/packages/silverstripe/business_directory

...or should they use their own name like this one:

https://packagist.org/packages/heyday/silverstripe-hashpath

...at the peril of making it even harder to locate modules.

Don't get me wrong, I'm really enjoying all the advanges that Composer gives us. I just want to start out getting this right, and get a little discussion on this running for all the module maintainers out there.

Thanks

Anselm

[Ryan Wachtl]

I struggled with this myself as I was adding a few of my packages last night. My understanding (reading from https://github.com/composer/composer/blob/master/doc/01-basic-usage.md#package-names) is that the package name is divided up into two parts; vendor and project.

VENDOR https://packagist.org/packages/heyday/silverstripe-hashpath

PROJECT https://packagist.org/packages/heyday/silverstripe-hashpath

When you install a package into a composer based SilverStripe project it will get placed into one of two places; either the root ("type": "silverstripe-module") or the themes directory ("type": "silverstripe-theme") and be unpacked into a directory with your project name. So, what I ended up doing was to use my vendor name (rywa) and the name of the directory that I wanted my package installed to. For example: rywa/foundation (which is a SilverStripe theme) will get installed into the themes directory into a folder called foundation.

I agree that it would be a lot easier to find packages if they were all in the silverstripe/my-package format, but at the same time it doesn't seem right to use "silverstripe" as the vendor name for our own packages/projects.

- Ryan

Ryan Wachtl

Twitter. @ryanwachtl

Skype. ryan.wachtl

www.linkedin.com/in/ryanwachtl

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To post to this group, send email to silverst...@googlegroups.com.
To unsubscribe from this group, send email to silverstripe-d...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.

[Andrew Short]

I'd suggest using the convention vendor/silverstripe-modulename, but with the module itself actually configured to install itself on the modulename directory.: so for me I'd release my modules as ajshort/silverstripe-modulename, but have it install to /modulename.

• This complies with the Packagist naming conventions.
• It means that we won't run into naming conflicts, an issue which has happened before.
• It makes it clear that third party modules are not released by SS the company.
  

Andrew Short.

[Ryan Wachtl]

That makes sense Andrew. How do we specify the name of the install directory within composer.json?

Ryan Wachtl

Twitter. @ryanwachtl

Skype. ryan.wachtl

www.linkedin.com/in/ryanwachtl

[Sam Minnée]

The other way to identify the modules would be with a "SilverStripe" tag.

Modifying the install directory would require submitting a pull request to composer/installers.

The "silverstripe-" prefix would make composer packages quite verbose. I know we did this for GitHub, but that was to make the meaning of forked repos more obvious. I'm not convinced that it's the best way of marking SilverStripe packages - a SilverStripe tag (as well as the package type being silverstripe-module or silverstripe-theme) seems more semantically useful.

There's also the matter of getting Vikas' work up and running in production. Of note, we could potentially rework that so that it took its module list by extracting all the appropriately tagged modules and themes from packagist. Then developers have one place to submit their modules.

[Ryan Wachtl]

Yes, that's the issue I ran into when trying to use the "silverstripe-" prefix, the directory my package would get installed to would have an ugly and unnecessarily long name with dashes in it. I agree that the "SilverStripe" tag (along with type) is probably our greatest asset for package discoverability.

Ryan Wachtl

Twitter. @ryanwachtl

Skype. ryan.wachtl

www.linkedin.com/in/ryanwachtl

[Sam Minnée]

I think it's important that we keep the vendor part of the name set to the person or organisation who leads the modules' development, or at least ego did initially if that changes.

The primary reason is to avoid namespace collisions. However, it also keeps us consistent with other Packagist packages. Also, when we do list all modules and themes on our own site, it will give more useful info.

I'd suggest that anyone who has put packages up with a silverstripe/ vendor prefix changes them before the install-base is too high. I think that it will be less confusing for everyone if we're consistent here.

[Nicolaas Thiemen Francken - Sunny Side Up]

Hmmmm, ok, I screwed up!  Thank you for pointing that out. 

before I correct my composer.json files, I would like to double-check best practice.  This is what I would like to put in my composer.json file:

name: sunnysideup/mymodule (NOTE: NOT sunnysideup/silverstripe-mymodule)

type: silverstripe-module (what do we do with widgets / themes ?)

description: bla bla

homepage: [my company website] / [a demo site] / ???

keywords: ["bla", "silverstripe", "foo"]

license: (name of license)

authors: (sub-array of name, homepage, email, role)

require: should we include

 - silverstripe/framework AND silverstripe/cms or just one of them?

 - php (or do we leave it to framework to set that requirement?)

 - in terms of versions, what is the best version we put 

   - how much detail (3.0.1 or 3.0.*, or  3.*)

   - should we say greater than (which may become incorrect as a new version is published) or equal to

extra: (screenshot ??)

support: 

   - issues: link

[Andrew Short]

I'd prefer to keep the silverstripe in the package name:

• Complies with the packagist naming conventions.
• Makes it clear that it's an SS module.
• Lets me see at a glance what silverstripe modules I have installed in a project - if I have "ajshort/twitter" installed in my composer.json file, it's not clear if this is a twitter silverstripe module, or a twitter API or something.

But I'm not too bothered either way - I think the main thing is not using silverstripe for the vendor name.

Andrew Short.

[Nicolaas Thiemen Francken - Sunny Side Up]

Lets document "best practice", whatever that is. 

[Anselm Christophersen]

So, I finally got to it, submitting my one theme, https://packagist.org/packages/titledk/cloudy

My question is now, how would anybody go about finding it?

I did a search, both on the packagist site to find Ryan Wachtl's foundation theme (https://packagist.org/packages/rywa/foundation), but if I hadn't know that it exists, I would never have found it.

Just searching like this, doesn't give very precise results: https://packagist.org/search/?q=silverstripe-theme

Are there any better ways of doing this, or is Packagist just not that mature yet?

I'm sure this will get better once the module listing on ss.org will get updated, but until then it seems exploring new modules and themes requires still a little bit of field research, and staying up to date on the social networks.

Anselm

[Dan Rye]

https://packagist.org/search/?tags[]=theme&tags[]=silverstripe

That will do it.  There aren't many yet.

[Uncle Cheese]

Did anyone clarify in this thread what we need to put in the composer.json to force a specific install directory?

[Andrew Short]

You can set the installer-name in the extra section: see https://github.com/ajshort/silverstripe-gridfieldextensions/blob/master/composer.json for an example.

Andrew Short.

--

You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.

To post to this group, send email to silverst...@googlegroups.com.

Visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Anselm Christophersen]

Great, thanks. That already makes Packagist a lot more useful for me.

On 05/02/2013, at 14.07, Dan Rye wrote:

https://packagist.org/search/?tags[]=theme&tags[]=silverstripe

That will do it.  There aren't many yet.

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.

To post to this group, send email to silverst...@googlegroups.com.

[Ryan Wachtl]

Nice! Just tried setting "installer-name" in "extras" and it worked like a charm. Looks like this was a recent addition in composer.

- Ryan

Ryan Wachtl

Twitter. @ryanwachtl

Skype. ryan.wachtl

www.linkedin.com/in/ryanwachtl