README and Plone versions [Add ons]

Would it an idea to extend out best practices for a README to have the version of Plone which is supported mentioned in the README ?

Sometimes it is kind of hard for integrators to find out which version of Plone is supported. Since the old software center will go away this is getting even harder :slightly_smiling:

IMHO this could be useful !

1 Like

I don't know why travis doesn't support it but it would be really nice if travis supported badges which said which versions were tested and passed.

+1! that would be really appreciated (although fixing the classifiers in setup.py would be even better :slight_smile:

+1! That will be a good way.

Yes, but usually Integrators do not check a setup.py, that is more for developers :slight_smile:

1 Like

https://github.com/plone/documentation/commit/52eae27d6c6efb5b9d434298125e83cf5600256c

Most people don't even read the README; what I do is set that in setup.py metadata to avoid installations on the wrong version.

for instance:

setup(
      ...
      classifiers=[
          ...
          'Framework :: Plone',
          'Framework :: Plone :: 4.2',
          'Framework :: Plone :: 4.3',
          ...
      ],
      ...
      install_requires=[
          ...
          'Products.CMFPlone >=4.2, <5.0',
          ...
      ],
      ...
      )

@hvelarde yes, but my intention is that a Integrator can see that, without reading a setup.py file, and the most Plone Integrators I know, checking these days the README, because they check on GitHub and not on plone.org/products.

Taking this further with the new future new plone.org and the query/feed about add-ons straight from pypi, we want something so that ppl easy can see which version of Plone is supported.

I a not saying that my idea is the best solution, so by all means if you have a better idea, please tell, but at least it would be a begin, at least if ppl start to use the best practices of a readme.

What you type in setup.py does end up on PyPI. For example look at https://pypi.python.org/pypi/eea.facetednavigation/8.8 and scroll all the way to the bottom and you will see which Plone versions are supported.
That is also the info that I expect will be parsed by the future query on plone.org.

But having it in more user friendly way in the readme is good, yes. I try to do that from time to time.

1 Like

exactly, having this information in more than one place and in different formats will lead to data inconsistency if someone forgets to update one of those files.

I get the point and yes, that is true, but we need also, maybe a different way, then to make it more user friendly.

If I look with the eyes of a person who is looking for a certain add on for my plone site, currently we are not 'user friendly' at all.

This is IMHO bad, there is a difference between developer/provider and a user who wants to install an add on.

As a user, I do not want to scroll down on pypi to find out which version is supported.

Personally I think a README is even not user friendly enough at all, but to be fair I opened this post with the question for an Integrator :slightly_smiling:

Yes, you are right that ppl may forget to update the README, this is the same problem that we have with /docs. But I also see ppl forgetting to upgrade their setup.py sometimes.

To solve this at least partly, we could write a test, that compares the version in setup.py with your versions in the README.

Yes, you can do ttd with documentation, just saying ::wink:

Or something in codeanalysis that compares Travis.yaml to what's in the readme and setup.py?

Sure, why not?

It may be a slight burden on developers and maintainers to have to mention version support in the README and in the setup.py classifiers.

what about adding some badges like these ones? http://shields.io/

we can create some sort of bridge between Python classifiers and a Plone 5 ready! image, for instance.

Ideally what you'd want is tiny app that scrapes travis to determine if version X of plone passed its test and returned a badge like [plone 4.x: passed]. or perhaps one badge which showed which versions passed [plone tested: 4.x, 5.x]