mockup-tocify rename?

[allcaps]

The name mockup-tocify and especially the mockup- prepend falsely suggests that his this package is part of Mockup. It is not! Mockup is a collection of patterns over at http://plone.github.io/mockup/dev/. We used mockup-minimalpattern as basis for mockup-tocify and therefore incorrectly reused the mockup- prefix in it's name.

During Plone Conf Bucharest 2015 there was some debate if all community patterns should have their own prefix or even should live in a separate Github organisation (some say the collective holds to many packages)... @thet: Is there consensus on this yet?

I would like:

• mockup-tocify to be part of Mockup as it is more advanced then http://plone.github.io/mockup/dev/#pattern/autotoc
• to know if patternslib and mockup will be combined and into what.
• to know if there will be a preferred naming schema for patterns that do not belong to mockup / patternslib
• to rename mockup-tocify asap if necessary.

[instification]

I would suggest pat-{pattern-name} and call this pat-tocify

It makes it clear it is a pattern and is concise. It also aligns with the usage of the pattern, ie: class='pat-tocify'

There is already pat-fancytree and pat-handsontable in the collective.

[thet]

We did not discuss this issue to the end and thus did not come to a consensus yet.

But I agree with @instification as long as there is not Plone integration code in the pattern - or the Plone integration code is done optionally, so that is still works as a standalone pattern.

So, I suggest for JS only patterns to use the pat-{pattern-name} naming as shown above, and for Plone integration packages collective.pat_{pattern-name} (mind the underscore. a dash is problematic for python packages).

Actually, the plone integration - as long there are no custom z3cform widgets involved - is just a profile and a plone.resource zcml entry anyways. I'm not sure, if every we'd want for every pattern a corresponding Plone integration package. Maybe we can find something simpler. Except for more complicated ones, which need to interact with Plone as a backend - e.g. the pat-handsontables.

[allcaps]

In our case the Plone integration is just a profile (and I don't think that'll change any time soon) so pat-tocify it is.

[instification]

We had discussed the idea of including a navigation portlet with the package so I think it could also make sense to have a second product for Plone integration that depends on pat-tocify.

That way it can remain a pure pattern package and would be easier to integrate into patternslib should it be considered for inclusion.

I also quite like the idea of keeping the pattern as simple as possible so as to make it easier to understand for people learning patterns.

[allcaps]

Okay. Yes, forgot about the portlet.

BTW: Can you make me owner of this repo?

[instification]

Ok I think you should have admin access now, let me know if not.

Also, things like integration with less variables etc so the styling of the toc is consistent with whatever theme is being used. Can also envisage some kind of control panel item for setting default options of the pattern too.

[allcaps]

Yes, I'm owner too.

Another one for the wish list: stick-to-top-of-viewport-while-scrolling-feature.

[thet]

@jcbrand @vangheem @frapell any comment to the naming convention discussion?

[jcbrand]

+1 for pat-*

That's how external patternslib patterns' repos are also named. Too bad that dash is problematic for python packages.

[thet]

Thinking it over again, IIRC, it's not problematic if the package distribution name has a dash in it. It's only problematic, if the python package, that is imported has a dash. But actually, I did not try it out.

However - just another iteration of the same idea from above: we could name the repo pat-{pattern-name} and a containing python package pat_{pattern-name}. In there we could provide sub-packages for plone, pyramid, django, whatever. They contain the resource integration for each platform. The package distribution itself is registered on pypi under the name pat-{pattern-name}.

Example: one could import then like this: from pat_tocify import plone, or from pat_tocify import django.

However, I still think patterns should be without integration code for other platforms (what if some Java guy wants to have integration code for himself?). Patterns itself should be completly framework agnostic. On the other hand to have something like pat-tocify and collective.pat_tocify is also not what I want.

[jcbrand]

However, I still think patterns should be without integration code for other platforms

Yes, which is why I think the JS should ideally be separated from any Plone (or other) integration code, i.e. be in its own repo.

[allcaps]

I think we all agree that there will be a pat-{pattern-name} for the pattern itself. So it can have a life outside Plone. In this case: pat-tocify.

Naming the Plone specific is harder... https://www.python.org/dev/peps/pep-0423/ says:

• Prefix with collective is good. (Makes it community owned and Plone specific)
• Not more than 2 levels deep. (NOT: collective.pat.tocify)
• Try to keep package and project name the same. (rules out the dash).

The examples in PEP-0423 also have multi word names without spaces, all lowercase. In our case: collective.pattocify

Which will also work for other names. Eg: The Plone stuff of pat-fanytree can live in collective.patfanytree and pat-handsontable in collective.pathandsontable.

This seems reasonable to me. @jcbrand and @thet does this sound okay to you?

[instification]

Do we need to include the pat on the plone package? It seems to me like collective.tocify would make sense.

Just because it uses the pattern doesn't mean it has to have it in the name. I personally like the idea of keeping it as concise as possible.

[jcbrand]

+1 @instification

[thet]

+1 from me too. Makes a lot of sense, since other collective.* libs might get updated to use patterns too.

[allcaps]

The idea of a shared prefix is that you can search for patterns more easily. But I don't find it a valid reason. Plone specific code for including a pattern is no different than any other Plone add on product.

Yes, concise is better. Hooray for collective.tocify.

[allcaps]

Done. Don't forget to set the new url:

git remote set-url origin git@github.com:collective/collective.tocify.git

[thet]

The naming convention for patterns and plone integration packages should be documented somewhere. I found this document for being a possible candidate to put the info to: http://docs.plone.org/develop/coredev/docs/style.html - but not exactly, since it's about the core style guide and not addon style guide. @polyester knows better..?

Feels someone like wanting to take responsibility for this?

[allcaps]

Related https://github.com/plone/documentation/issues/302

I'll also add a line and a reference to this issue in the spint docs.google document.

[polyester]

We have a bit of a mish-mash now, there are styleguides at http://docs.plone.org/develop/coredev/docs/style.html, and then coding styleguides at https://github.com/plone/plone.api/blob/master/docs/contribute/conventions.rst (which have been sort of doubling as add-on styleguide as well) and then there is meta-style like 'how to name your packages, patterns, etcetera'.

I think it's time to start a new chapter (=folder) 'styleguide' under docs.plone.org/develop/ and then have separate entries for these here, so one file python.rst for python styleguide, docs.rst for documentation styleguide for add-on packages, naming.rst for naming conventions and an index.rst to list them all.

[thet]

+1, @polyester - good plan

[instification]

@jcbrand @thet should the pat-tocify package (pure patternslib) go in the Patternslib repo github.com/Patternslib? Or just in the collective?

I guess we could move it fairly easily but it would make sense to have a home for pure patternslib patterns.

[jcbrand]

@instification I'm happy if it goes into Patternslib repo. However, it should then adhere to the Patternslib styleguide and conventions.

http://patternslib.com/pattern-styleguide/#main-content

The styleguide is incomplete and needs expanding. It's on my TODO list and I'll try to get to it ASAP.

One easy way to check for minimal compatibility is to copy the .jshint file from Patterns repo and put that in your own and then do a check.

Another easy way to get the pattern to adhere to conventions is to use the Yeoman generator to generate the package layout (you can then copy your pattern into the src dir). https://www.npmjs.com/package/generator-patternslib

@thet has fixed some bugs there and we made a new release yesterday.

[polyester]

on styleguides: I've made an initial home for them in the branch 'styleguides' at https://github.com/plone/documentation/tree/styleguides/develop/styleguide. WIP, I'll try to assemble what we have over the weekend, but new stuff (javascript styleguide? yes please!) can go in there.

[jcbrand]

@thet I've updated the Patternslib coding style guide: http://patternslib.com/pattern-styleguide/#main-content

It should now be mostly complete.

@polyester I'm happy to add the Patternslib Javascript coding styleguide to plone docs as well. Challenge is that the Mockup coding style is much different than the Patternslib style :(

[polyester]

@jcbrand is there a Mockup coding styleguide or was it just coded in different way? Can't find one for Mockup. And since both projects now are getting closer again, it seems to make sense to have one guide for both, and future Mockup dev should follow that. Then again, I'm not in the mockup devs...

[jcbrand]

I'll add the styleguide to Plone docs (mentioning differences) and we'll go from there...

[jcbrand]

@polyester I've finally added a Javascript styleguide for Plone. See here: https://github.com/plone/documentation/commit/b1b973c4234bde0f4c6c4b31327cd2fabc03dd73