Merge pull request #52 from collective/maurits/no-travis-cfg-in-docs

Removed travis-5.2.x.cfg and updated docs

README.rst

@@ -6,40 +6,56 @@ Testing/development buildouts for Plone
 
 This repository contains a number of configuration files for using
 `zc.buildout`_ to quickly set up a testing/development environment for your
-package.  The intended usage is to create a ``buildout.cfg`` like::
+package.
+
+A good example of how to use this, is `bobtemplates.plone <https://github.com/plone/bobtemplates.plone>`_.
+Follow the instructions there to create a Plone add-on, and look at the created files,
+especially the various buildout configs and `.travis.yml <https://github.com/plone/bobtemplates.plone/blob/master/bobtemplates/plone/addon/.travis.yml.bob>`_.
+
+The intended usage is to create a ``buildout.cfg`` like::
 
     [buildout]
-    extends = https://raw.github.com/collective/buildout.plonetest/master/test-4.x.cfg
+    extends = https://raw.github.com/collective/buildout.plonetest/master/test-5.x.cfg
     package-name = plone.app.foo
 
-Running buildout should give you a ``bin/test`` script, which can be used to
+Create a virtualenv and run buildout.
+This should give you a ``bin/test`` script, which can be used to
 run your package's tests.  If your tests have additional dependencies, you
 should declare them via the ``extras_require`` parameter of
 ``setuptools.setup`` and refer to the key used using the ``package-extras``
 variable::
 
     [buildout]
-    extends = https://raw.github.com/collective/buildout.plonetest/master/test-4.x.cfg
-    package-name = plone.app.foo
-    package-extras = [test]
-
-If you want to do `continuous integration`_ with `Travis CI`_ you should
-create a ``travis.cfg`` like::
-
-    [buildout]
-    extends = https://raw.github.com/collective/buildout.plonetest/master/travis-4.x.cfg
+    extends = https://raw.github.com/collective/buildout.plonetest/master/test-5.x.cfg
     package-name = plone.app.foo
     package-extras = [test]
 
+If you want to do `continuous integration`_ with `Travis CI`_ you can use this same buildout config.
 And a ``.travis.yml`` like::
 
     language: python
     python: 2.7
+    sudo: false
+    cache:
+      pip: true
+      directories:
+        - eggs
+    before_install:
+      - virtualenv -p `which python` .
+      - bin/pip install -r requirements.txt
+      - bin/buildout -N -t 3 annotate
     install:
-      - mkdir -p buildout-cache/downloads
-      - python bootstrap.py -c travis.cfg
-      - bin/buildout -N -t 3 -c travis.cfg
-    script: bin/test
+      - bin/buildout -N -t 3
+    script:
+      - bin/test
+
+.. ATTENTION::
+   This repository also has ``travis-*.cfg`` files, that try to be faster by downloading the Plone universal installer.
+   This is no longer recommended, because Travis meanwhile has better caching support.
+   Only the Travis config files for Plone 5.1 and earlier have been kept, to avoid breaking add-ons.
+   In your own buildout config, replace ``travis-*.cfg`` with ``test-*.cfg`` and you should be fine.
+   Also take over the ``cache`` setting from the ``.travis.yml`` file above.
+
 
 i18ndude helper script to update po files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -48,21 +64,25 @@ Include the following in your buildout configuration to create an `i18ndude`_
 helper script to update the po files of your product::
 
     [buildout]
-    parts =
-        ...
+    extends =
+        https://raw.github.com/collective/buildout.plonetest/master/test-5.x.cfg
+        https://raw.github.com/collective/buildout.plonetest/master/qa.cfg
+    package-name = plone.app.foo
+    package-extras = [test]
+    parts+=
+        i18ndude
         rebuild_i18n-sh
 
-    [rebuild_i18n-sh]
-    recipe = collective.recipe.template
-    url = https://raw.github.com/collective/buildout.plonetest/master/templates/rebuild_i18n.sh.in
-    output = ${buildout:directory}/bin/rebuild_i18n.sh
-    mode = 755
-
-After running 'bin/buildout' you will find a 'bin/rebuild_i18n.sh'; run the
+After running ``bin/buildout`` you will find a ``bin/rebuild_i18n.sh``; run the
 script and the po files will be updated.
 
-Domain name is taken from the ${buildout:package-name} variable; Plone domain
-is also included.
+Domain name is taken from the ``${buildout:package-name}`` variable.
+The plone domain is also included.
+
+.. ATTENTION::
+   Originally, the ``rebuild_i18n-sh`` part used a `filesystem template <https://github.com/collective/buildout.plonetest/blob/master/templates/rebuild_i18n.sh.in>`_.
+   This is deprecated and no longer updated.
+
 
 Functional tests with Robot Framework and SeleniumLibrary in Travis CI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -73,45 +93,77 @@ Update your ``.travis.yml`` file with the following::
       - export DISPLAY=:99.0
       - sh -e /etc/init.d/xvfb start
 
-Testing in Travis CI with multiple versions of Plone
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``travis.cfg`` file in your package should look like this::
+Testing in Travis CI with multiple versions of Plone and Python
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``buildout.cfg`` file in your package should look like this::
 
     [buildout]
     extends =
-        https://raw.github.com/collective/buildout.plonetest/master/travis-4.x.cfg
+        https://raw.github.com/collective/buildout.plonetest/master/test-5.x.cfg
 
     package-name = collective.foo
     package-extras = [test]
 
-    allow-hosts +=
-        code.google.com
-        robotframework.googlecode.com
+    [versions]
+    setuptools = 41.2.0
+    zc.buildout = 2.13.2
+
+The versions are optional, but they can help in avoiding restarts when buildout tries to upgrade itself to a version pinned in Plone.
+It is fine to start without them, but when you run into problems in `Travis CI`_, consider adding them.
+In this way, all Plone versions use the same buildout and setuptools versions.
+
+These versions match a ``requirements.txt`` like this::
 
-And the ``.travis.yml`` file should look like this::
+    setuptools==41.2.0
+    zc.buildout==2.13.2
 
+The ``.travis.yml`` file should look like this::
+
+    dist: bionic
     language: python
     python: 2.7
-    env:
-      - PLONE_VERSION=4.2
-      - PLONE_VERSION=4.3
+    sudo: false
+    cache:
+      pip: true
+      directories:
+        - eggs
+    matrix:
+      include:
+        - python: "2.7"
+          env: PLONE_VERSION="4.3"
+        - python: "2.7"
+          env: PLONE_VERSION="5.1"
+        - python: "2.7"
+          env: PLONE_VERSION="5.2"
+        - python: "3.7"
+          env: PLONE_VERSION="5.2"
+        - python: "3.7"
+          env: PLONE_VERSION="5.2"
+      sudo: true
+      fast_finish: true
+    before_install:
+      - virtualenv -p `which python` .
+      - bin/pip install -r requirements.txt
+      - sed -ie "s#test-5.x.cfg#test-$PLONE_VERSION.x.cfg#" buildout.cfg
+      - bin/buildout -N -t 3 annotate
     install:
-      - sed -ie "s#travis-4.x.cfg#travis-$PLONE_VERSION.x.cfg#" travis.cfg
-      - mkdir -p buildout-cache/downloads
-      - python bootstrap.py -c travis.cfg
-      - bin/buildout -c travis.cfg -N -q -t 3
-    script: bin/test
+      - bin/buildout -N -t 3
+    script:
+      - bin/test
 
 The trick here is to replace the extended configuration with the right one
 using the `sed`_ command.
 
+
 Experimental configurations
 ===========================
 
 .. Caution::
     The following configurations are experimental and may change at any time.
 
+
 Quality Assurance
 ^^^^^^^^^^^^^^^^^
 
@@ -120,7 +172,7 @@ update your ``travis.cfg`` file like::
 
     [buildout]
     extends =
-        https://raw.github.com/collective/buildout.plonetest/master/travis-4.x.cfg
+        https://raw.github.com/collective/buildout.plonetest/master/test-5.x.cfg
         https://raw.github.com/collective/buildout.plonetest/master/qa.cfg
     package-name = plone.app.foo
     package-extras = [test]
@@ -130,23 +182,29 @@ update your ``travis.cfg`` file like::
         coverage-sh
         code-analysis
 
-and add and commit ``.coveragerc`` file 
-(see example at https://github.com/plone/plone.recipe.codeanalysis/blob/master/.coveragerc) 
+and add and commit ``.coveragerc`` file
+(see example at https://github.com/plone/plone.recipe.codeanalysis/blob/master/.coveragerc)
 
 and update your ``.travis.yml`` like::
 
     language: python
     python: 2.7
+    sudo: false
+    cache:
+      pip: true
+      directories:
+        - eggs
     env:
       - TARGET=test
       - TARGET=coverage.sh
-
-    install: 
-      - mkdir -p buildout-cache/downloads
-      - python bootstrap.py -c travis.cfg
-      - bin/buildout -c travis.cfg -N -q -t 3
-    
-    script: bin/$TARGET
+    before_install:
+      - virtualenv -p `which python` .
+      - bin/pip install -r requirements.txt
+      - bin/buildout -N -t 3 annotate
+    install:
+      - bin/buildout -N -t 3
+    script:
+      - bin/$TARGET
 
 .. _`continuous integration`: https://en.wikipedia.org/wiki/Continuous_integration
 .. _`i18ndude`: http://pypi.python.org/pypi/i18ndude/

travis-5.x.cfg

@@ -1,7 +1,11 @@
-[buildout]
-extends = test-5.x.cfg buildout-cache.cfg
-parts = download install test
-plone-series = 5.1
-package-name =
-package-extras =
-test-eggs =
+This file is DEPRECATED and must not be used anymore.
+Please see README.rst for current instructions on how to use buildout.plonetest.
+
+Note: the other travis-*.cfg files will be kept for now.
+So if you really want, you can switch to travis-5.1.x if you only want to test Plone 5.1.
+But these travis files will not work for Plone 5.2.
+
+For information about the change, see this issue:
+https://github.com/collective/buildout.plonetest/issues/10
+And see this PR:
+https://github.com/collective/buildout.plonetest/pull/52