Просмотр исходного кода

Clarify plugin contribution docs

Justin Mayer лет назад: 9
Родитель
Сommit
eeae883394
1 измененных файлов с 19 добавлено и 11 удалено
  1. 19 11
      Contributing.rst

+ 19 - 11
Contributing.rst

@@ -1,31 +1,39 @@
 Contributing a plugin
 Contributing a plugin
 =====================
 =====================
 
 
-Details of how to write a plugin is explained in the official Pelican `docs`_.
+Details regarding how to write a plugin are explained in the Pelican `docs`_.
 
 
-If you want to contribute, please fork this repository and issue your pull
-request. Make sure that your plugin follows the structure below::
+If you want to contribute, **please be sure to read our general contributing
+`guidelines`_ first**. Then you can fork this repository, create a new branch,
+make your changes, squash your commits, and issue your pull request from your
+new branch (i.e., **not** the ``master`` branch).
+
+Make sure that your plugin follows the structure below::
 
 
     my_plugin
     my_plugin
        ├──  __init__.py
        ├──  __init__.py
        ├──  my_plugin.py
        ├──  my_plugin.py
        ├──  test_my_plugin.py
        ├──  test_my_plugin.py
-       └──  Readme.rst / Readme.md
-
+       └──  ReadMe.rst / ReadMe.md
 
 
 ``my_plugin.py`` is the actual plugin implementation. Include a brief
 ``my_plugin.py`` is the actual plugin implementation. Include a brief
-explanation of what the plugin does as a module docstring. Leave any further
-explanations and usage details to ``Readme`` file.
+explanation of what the plugin does as a module docstring. Put any further
+explanations and usage details into the ``ReadMe`` file.
 
 
 ``__init__.py`` should contain a single line with ``from .my_plugin import *``.
 ``__init__.py`` should contain a single line with ``from .my_plugin import *``.
 
 
-Place tests for your plugin in the same folder with name ``test_my_plugin.py``.
-You can use ``test_data`` main folder, if you need content or templates in your tests.
+Place tests for your plugin in the same folder inside ``test_my_plugin.py``.
+If you need content or templates in your tests, you can use the main
+``test_data`` folder for that purpose.
 
 
 **Note:** Each plugin can contain a LICENSE file stating the license it's
 **Note:** Each plugin can contain a LICENSE file stating the license it's
 released under. If there is an absence of LICENSE then it defaults to the
 released under. If there is an absence of LICENSE then it defaults to the
-*GNU AFFERO GENERAL PUBLIC LICENSE Version 3*.
+*GNU AFFERO GENERAL PUBLIC LICENSE Version 3*. Please refer to the ``LICENSE``
+file for the full text of the license.
 
 
-Please refer to the ``LICENSE`` file for the full text of the license.
+Before making your initial commit, please be sure to add an entry to the repo's
+top-level ``ReadMe`` file, adding your plugin to the list (in alphabetical
+order) and providing a brief description.
 
 
+.. _guidelines: http://docs.getpelican.com/en/latest/contribute.html#using-git-and-github
 .. _docs: http://docs.getpelican.com/en/latest/plugins.html#how-to-create-plugins
 .. _docs: http://docs.getpelican.com/en/latest/plugins.html#how-to-create-plugins