소스 검색

Clarify plugin contribution docs

Justin Mayer 9 년 전
부모
커밋
eeae883394
1개의 변경된 파일19개의 추가작업 그리고 11개의 파일을 삭제
  1. 19 11
      Contributing.rst

+ 19 - 11
Contributing.rst

@@ -1,31 +1,39 @@
 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
        ├──  __init__.py
        ├──  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
-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 *``.
 
-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
 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