plone · fgrcon · Mar 31, 2016 · Jun 1, 2016 · Jun 2, 2016 · Jun 7, 2016
diff --git a/.coafile b/.coafile
@@ -0,0 +1,15 @@
+[WG]
+bears = WriteGoodLintBear
+allow_so_beginning = False
+files = **/*.rst
+
+#[LC]
+#bears = LineCountBear
+#max_lines_per_file = 1000
+#files = **/*.rst
+
+#[QA]
+#bears = SpaceConsistencyBear
+#use_spaces = True
+#files = **/*.rst
+#default_actions = SpaceConsistencyBear: ApplyPatchAction
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,4 @@ _locales
 develop/coredev
 develop/plone.api
 develop/addons/bobtemplates.plone
-
+.project
diff --git a/.travis.yml b/.travis.yml
@@ -5,22 +5,21 @@ sudo: false
 before_install:
 - export DISPLAY=:99.0
 - sh -e /etc/init.d/xvfb start
-- curl -O http://www.abisource.com/downloads/enchant/1.6.0/enchant-1.6.0.tar.gz
-- tar xzvf enchant-1.6.0.tar.gz
+- curl -SLk https://www.abisource.com/downloads/enchant/1.6.0/enchant-1.6.0.tar.gz | tar xvz
 - cd enchant-1.6.0
 - ./configure --prefix=`pwd`
 - make install
 - cd ..
 install:
 - git clone https://github.com/plone/papyrus ../papyrus && cd ../papyrus
+- virtualenv . && source bin/activate
 - mkdir -p source && ln -s ../../documentation source/documentation
-- python bootstrap-buildout.py --setuptools-version=18.3.1 --version=2.4.3
+- pip install zc.buildout
 - bin/buildout -N -t 3 buildout:eggs-directory=../eggs buildout:checkout=documentation sources:documentation="git https://github.com/plone/documentation egg=false" versions:plone.app.robotframework=0.9.14
 before_script:
 - echo '[general]' > docutils.conf
 - echo 'report_level = 5' >> docutils.conf
 script:
-- make screenshots
 - LANGS=en make html
 after_script:
 cache:

diff --git a/.ttd-lintrc b/.ttd-lintrc
@@ -0,0 +1,2 @@
+Github
+Javascript
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -2,6 +2,46 @@
 Changelog
 =========
 
+
+Unreleased
+==========
+
+- Add security guidelines for developers[vangheem]
+- Overhaul of vocabularies section. [jensens]
+- Remove Deliverance info for theming and refer to diazo.org deployment [fredvd]
+- Improve ReStructuredText Style Guide [svx]
+- Add documentation about TinyMCE styles and formats [davilima6]
+- Documentation for Thumbs and Iconhandling in Plone 
+  https://github.com/plone/Products.CMFPlone/issues/1734 [fgrcon]
+
+20160606
+========
+
+- Improve documentation about PFG custom mailer [terapyon]
+- Update documentation about forms in add-ons [staeff]
+- Update documentation about add-on installation [svx]
+- Made isort.cfg more readable by adding spaces [mauritsvanrees]
+- Various .rst style fixes [svx]
+- Add documentation about browserlayer.xml [davilima6]
+- Add better examples for installation on various operating systems [svx]
+- Improve documentation about dexterity AddCoustomView and ZCML [terapyon]
+- Improve 'ask for help' docs [svx]
+- Improve wording and rst on various places [svx]
+- Improve docs about GenericSetup [mauritsvanrees]
+- Fix link [icemac]
+- Cleanup grok [staeff]
+- Update index.rst [fgrcon]
+- Fix various links [polyester]
+- Fix various links [gforcada]
+- Fix various typos [svx]
+- Fix various typos [gforcada]
+- Fix various typos [sverbois]
+- Fix various typos [staeff]
+- Add more docs about ZCML registration features [davidjb]
+- Various typo fixes [jianaijun]
+
+
+
 20160409
 ========
 
@@ -10,6 +50,7 @@ Changelog
 - Fix 588 [svx]
 - Fix 582 [svx]
 
+
 20160405
 ========
 
@@ -19,6 +60,7 @@ Changelog
 - Fix #583 [polyester]
 - Fix 'Feedback widget' [svx]
 
+
 20160330
 ========
 
@@ -46,7 +88,6 @@ Changelog
 - Added note about advanced settings tab only for current theme [thet]
 
 
-
 20151208
 ========
 

diff --git a/_static/contents-with-thumbs-suppressed.png b/_static/contents-with-thumbs-suppressed.png
diff --git a/_static/contents-with128x128.png b/_static/contents-with128x128.png
diff --git a/_static/feedback_widget_right.png b/_static/feedback_widget_right.png
diff --git a/_static/icons.png b/_static/icons.png
diff --git a/_static/icons2.png b/_static/icons2.png
diff --git a/_static/thumbs-example-1.png b/_static/thumbs-example-1.png
diff --git a/_templates/doormat.html b/_templates/doormat.html
@@ -21,7 +21,7 @@
       About this documentation:
         <ul class="list-unstyled">
           <li><a href="http://docs.plone.org/about/contributing.html#id6">Contribute</a></li>
-          <li><a href="https://github.com/plone/documentation">These docs on Github</a></li>
+          <li><a href="https://github.com/plone/documentation">These docs on GitHub</a></li>
         </ul>
       </div>
       <div class="col-xs-6 col-sm-3">

diff --git a/_templates/version_warning.html b/_templates/version_warning.html
@@ -2,8 +2,8 @@
 <div class="row">
   <div class="col-sm-12 admonition warning version_warning" >
     <p class="first admonition-title">Warning</p>
-   <p class="last">This is the documentation for the just-released Plone 5, and is updated regularly.<br />
-    There have been many changes in this version, so if you are using Plone 4 do consult the <a href="http://docs.plone.org/4/en">Plone 4.3 Documentation</a></p>
+   <p class="last">This is the documentation for the just-released Plone 5.1, and is updated regularly.<br />
+    There have been many changes in this version, if you are using Plone 4 do consult the <a href="http://docs.plone.org/4/en">Plone 4.3 Documentation</a></p>
   </div>
 </div>
 {% endblock %}
diff --git a/about/cherrypicking.rst b/about/cherrypicking.rst
@@ -0,0 +1,38 @@
+=====================================
+Add your changes to multiple branches
+=====================================
+
+.. admonition:: Description
+
+   How to cherry-pick your changes from one branch to another branch.
+
+
+As this documentation is kept for multiple Plone versions,
+there are times when a pull request should be merged to more than one branch.
+
+Follow these simple steps to do so.
+
+Make the changes targeting the latest release and create a pull request.
+
+Once the pull request gets merged,
+get to your terminal and *cherry-pick* the commits on the other branches.
+
+For example,
+after your pull request with one single commit (commit id ``abcdef``) on branch 5.1 got merged,
+do the following to bring those changes to branch 5.0
+
+.. code-block:: shell
+
+    git clone [email protected]:plone/documentation
+    cd documentation
+    git checkout 5.0
+    git cherry-pick abcdef
+    git push
+
+If it should go to even more branches, repeat the last three steps above.
+
+If there are more than one single commit in the pull request,
+repeat the :command:`cherry-pick` command as many times as needed.
+
+.. note::  If the cherry-pick fails to apply the commit cleanly,
+   you can use a diff tool to see what's the problem and solve it as usually you do with code.
diff --git a/about/contributing.rst b/about/contributing.rst
@@ -1,14 +1,11 @@
-==================================
- Contributing to the documentation
-==================================
+=================================
+Contributing to the documentation
+=================================
 
 .. admonition:: Description
 
    How to write and submit content for the Plone Documentation.
 
-.. contents:: :local:
-
-
 
 Reaching the documentation team
 ===============================
@@ -27,25 +24,66 @@ Feedback
 
 We love your feedback! In order to improve the documentation we need your feedback and your help.
 
-If you have already a GitHub account, please do not hesitate to open a ticket on `GitHub <https://github.com/plone/documentation/issues>`_ .
+If you have already a GitHub account, please do not hesitate to open a ticket in our `issue tracker <https://github.com/plone/documentation/issues>`_ .
 
-If you do not have one, please use the 'Feedback' widget on http://docs.plone.org.
+If you do not have one, please use the 'Feedback' widget on `docs.plone.org <http://docs.plone.org>`_ .
 
-.. image:: /_static/feedback.png
+.. image:: /_static/feedback_widget_right.png
    :align: center
    :alt: Picture of feedback widget
 
+Reporting Issues
+================
+
+Documentation Issues
+--------------------
+
+Documentation issues are tracked in our `issue tracker <https://github.com/plone/documentation/issues>`_.
+
+If you have already a `GitHub <https://github.com>`_ account and you find something missing or wrong in the docs, please open a ticket.
+
+If you would like to contribute to the documentation and looking for a starting point,
+please browse to our `issue board <https://github.com/plone/documentation/projects/1?fullscreen=true>`_.
+
+Issues are sorted into different levels from easy to advanced. Picking an easy one is a great way to get started.
+
+.. note::
+
+    Working on issues takes time and energy, to make it as pleasant as possible for everyone,
+    meaning for you and the reviewer we would like to ask you kindly to make yourself familiar with our
+    style-guides for :doc:`documentation </about/documentation_styleguide>` and :doc:`reStructuredText [reST]</about/rst-styleguide>`.
+
+Plone Issues
+------------
+
+If you think your bug involves a core component of Plone, check to see if that component
+has its own repository at `GitHub <https://github.com/plone>`_.
+
+If it does, use the component's issue tracker to submit your bug report.
+If the component does not have its own repository there, submit your bug report
+in `the catch-all CMFPlone tracker on GitHub <https://github.com/plone/Products.CMFPlone/issues>`_.
+
+Note: after figuring out where to post your report, but before doing so,
+please search the issue tracker to ensure this issue hasn't already been reported and that it hasn't already been fixed in a later version of the component.
+
+You can also find a `overview <https://plone.org/support/bugs>`_ about that on `plone.org <https://plone.org>`_.
+
+
 
 License
 =======
 
 The Plone Documentation by `Plone Foundation <https://plone.org>`_ is licensed under a `Creative Commons Attribution 4.0 International License <http://creativecommons.org/licenses/by/4.0/>`_.
 
-If you want to contribute to this documentation, you can do so directly by making a pull request, if you have filled out a `Contributor Agreement <https://plone.org/foundation/contributors-agreement>`_.
+If you want to contribute to this documentation, you can do so directly by making a pull request,
+if you have filled out a `Contributor Agreement <https://plone.org/foundation/contributors-agreement>`_.
+
+If you haven't filled in a Contributor Agreement, you can still contribute. Contact the Documentation team,
+for instance via our `community space <https://community.plone.org/c/documentation/>`_.
 
-If you haven't filled in a Contributor Agreement, you can still contribute. Contact the Documentation team, for instance via the `mailinglist <http://sourceforge.net/p/plone/mailman/plone-docs/>`_ or directly send a mail to [email protected]
-Basically, all we need is your written confirmation that you are agreeing your contribution can be under Creative Commons. You can also add in a comment with your pull request "I, <full name>, agree to have this published under Creative Commons 4.0 International BY".
+Basically, all we need is your written confirmation that you are agreeing your contribution can be under Creative Commons.
 
+You can also add in a comment with your pull request "I, <full name>, agree to have this published under Creative Commons 4.0 International BY".
 
 Workflow
 ========
@@ -62,9 +100,13 @@ For these reasons, it is important we keep the documentation coherent.
 Therefore, we follow a simple workflow, which we ask all contributors to respect:
 
 
-Please  **DO NOT** commit to master directly. Even for the smallest and most trivial fix. **ALWAYS** open a pull request and ask somebody else to merge your code. **NEVER** merge it yourself.
+Please  **DO NOT** commit to master directly. Even for the smallest and most trivial fix.
+
+**ALWAYS** open a pull request and ask somebody else to merge your contribution. **NEVER** merge it yourself.
 
-Your pull requests may be checked for spelling, and clarity. So don't hesitate to contribute also if English is not your first language, we will try to be helpful in corrections without being annoying.
+
+Your pull requests may be checked for spelling, and clarity.
+Don't hesitate to contribute also if English is not your first language, we will try to be helpful in corrections without being annoying.
 
 If you don't get feedback on your pull request in a day please come to #plone-docs and ask.
 
@@ -82,8 +124,11 @@ The documentation for the different versions (Plone 3, Plone 4, Plone 5) are org
 
 The *default* branch points to the current version of Plone.
 
-Documentation changes that are valid for multiple versions of Plone can be done by making multiple pull requests, or by *cherry-picking* which may be easier to do when branches are widely different.
-When all this seems alien and strange, just note in your pull request that you think this is valid for other versions of Plone as well, and the documentation team will take care of doing the technical stuff.
+Documentation changes that are valid for multiple versions of Plone can be done by making multiple pull requests, or by :doc:`cherry-picking </about/cherrypicking>`
+which may be easier to do when branches are widely different.
+
+When all this seems complicated, note in your pull request that you think this is valid for other versions of Plone as well,
+and the documentation team will take care.
 
 
 Editing the documentation on GitHub
@@ -161,7 +206,6 @@ Translation
 ===========
 
 We use `Transifex <https://www.transifex.com/>`_ for translation.
-Thanks to that it is really easy to contribute to translation.
 
 Quick start:
 ------------
@@ -183,7 +227,3 @@ Getting started
 * Choose your language
 
 * Click on the right *Join Team*
-
-
-
-
diff --git a/about/documentation_styleguide.rst b/about/documentation_styleguide.rst
@@ -6,7 +6,6 @@ Documentation Styleguide
 
     A guide to write Documentation for Plone and for Plone Add-ons
 
-.. contents:: :local:
 
 Introduction
 ============
@@ -70,10 +69,12 @@ For including documentation into docs.plone.org, **please** follow these guideli
 * The '/docs' directory should contain **only** content related to documentation, please do **not** put the license here.
   A LICENSE.rst with a short description of the license, and LICENSE.GPL for the legalese should go into the top level of your package next to your README.rst
 
-* Please follow this :doc:`ReST styleguide <rst-styleguide>` and use **semantic linefeeds**.
+* Please follow this :doc:`rst-styleguide` and use **semantic linefeeds**.
   Do **not** break your sentences into half with newlines because you somehow think you should follow PEP8.
   PEP8 is for Python files, not for ReStructuredText.
 
+* Please follow our :doc:`word_choice`.
+
 * Usage of `Sphinx <http://sphinx-doc.org/>`_ within your project is optional, but if you want your add-on to (also) be documented for instance on `Read The Docs <https://readthedocs.org/>`_ it is highly recommended. Put the associated Makefile and conf.py into the /docs directory.
 
 

diff --git a/about/helper_tools.rst b/about/helper_tools.rst
@@ -6,21 +6,16 @@ Helper tools for writing Documentation
 
    Tools and Plugins which will help to write documentation.
 
-.. contents:: :local:
 
-
-
-
-
-Online tools:
--------------
+Online tools
+============
 
 - `rst.ninjs.org <http://rst.ninjs.org/>`_ and a fork with more Sphinx support at `livesphinx.herokuapp.com <http://livesphinx.herokuapp.com/>`_
 - `notex.ch <https://www.notex.ch/>`_
 
 
-Offline tools:
----------------
+Offline tools
+=============
 
 **ReText** is a handy editor for **.rst** and **.md** formats.
 On Ubuntu and Debian-based systems all you have to do is
@@ -71,8 +66,8 @@ A viewer for ReStructuredText documents that renders them on the fly.
 
     pip install restview
 
-Language tools:
----------------
+Language tools
+==============
 
 These tools can help you to check for grammatical mistakes and typos, you should always use a spell checker anyway!
 

diff --git a/about/index.rst b/about/index.rst
@@ -5,15 +5,9 @@ About this documentation
 .. toctree::
     :maxdepth: 2
 
-    reading
     contributing
     documentation_styleguide
     rst-styleguide
+    word_choice
     helper_tools
     searching
-
-Changelog
----------
-
-.. toctree::
-    :maxdepth: 2