diff options
| -rw-r--r-- | CONTRIBUTING.rst | 5 | ||||
| -rw-r--r-- | docs/contribute.rst | 180 |
2 files changed, 105 insertions, 80 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7ae47593..ac120128 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -137,8 +137,7 @@ Contribution quality standards code/formatting can be improved. If you are relying on your editor for PEP8 compliance, note that the line length specified by PEP8 is 79 (excluding the line break). -* Ensure your code is compatible with the latest Python 2.7 and 3.x releases — see our - `compatibility cheatsheet`_ for more details. +* Ensure your code is compatible with the `officially-supported Python releases`_. * Add docs and tests for your changes. Undocumented and untested features will not be accepted. * `Run all the tests`_ **on all versions of Python supported by Pelican** to @@ -155,4 +154,4 @@ need assistance or have any questions about these guidelines. .. _`Git Tips`: https://github.com/getpelican/pelican/wiki/Git-Tips .. _`PEP8 coding standards`: https://www.python.org/dev/peps/pep-0008/ .. _`ask for help`: `How to get help`_ -.. _`compatibility cheatsheet`: https://docs.getpelican.com/en/latest/contribute.html#python-3-development-tips +.. _`officially-supported Python releases`: https://devguide.python.org/#status-of-python-branches diff --git a/docs/contribute.rst b/docs/contribute.rst index 5a314751..1e884463 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -7,72 +7,78 @@ can also help out by reviewing and commenting on `existing issues <https://github.com/getpelican/pelican/issues>`_. Don't hesitate to fork Pelican and submit an issue or pull request on GitHub. -When doing so, please adhere to the following guidelines. +When doing so, please consider the following guidelines. .. include:: ../CONTRIBUTING.rst Setting up the development environment ====================================== -While there are many ways to set up one's development environment, we recommend -using `Virtualenv <https://virtualenv.pypa.io/en/stable/>`_. This tool allows -you to set up separate environments for separate Python projects that are -isolated from one another so you can use different packages (and package -versions) for each. +While there are many ways to set up one's development environment, the following +instructions will utilize Pip_ and Poetry_. These tools facilitate managing +virtual environments for separate Python projects that are isolated from one +another, so you can use different packages (and package versions) for each. -If you don't have ``virtualenv`` installed, you can install it via:: +Please note that Python 3.6+ is required for Pelican development. - $ pip install virtualenv +*(Optional)* If you prefer to install Poetry once for use with multiple projects, +you can install it via:: -Use ``virtualenv`` to create and activate a virtual environment:: + curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python - $ virtualenv ~/virtualenvs/pelican - $ cd ~/virtualenvs/pelican - $ . bin/activate +Point your web browser to the `Pelican repository`_ and tap the **Fork** button +at top-right. Then clone the source for your fork and add the upstream project +as a Git remote:: -Clone the Pelican source into a subfolder called ``src/pelican``:: + mkdir ~/projects + git clone https://github.com/YOUR_USERNAME/pelican.git ~/projects/pelican + cd ~/projects/pelican + git remote add upstream https://github.com/getpelican/pelican.git - $ git clone https://github.com/getpelican/pelican.git src/pelican - $ cd src/pelican +While Poetry can dynamically create and manage virtual environments, we're going +to manually create and activate a virtual environment:: -Install the development dependencies:: + mkdir ~/virtualenvs + python3 -m venv ~/virtualenvs/pelican + source ~/virtualenvs/pelican/bin/activate - $ pip install -r requirements/developer.pip +Install the needed dependencies and set up the project:: -Install Pelican and its dependencies:: + pip install -e ~/projects/pelican invoke + invoke setup - $ python setup.py develop +Your local environment should now be ready to go! -Or using ``pip``:: +.. _Pip: https://pip.pypa.io/ +.. _Poetry: https://poetry.eustace.io/docs/#installation +.. _Pelican repository: https://github.com/getpelican/pelican - $ pip install -e . +Development +=========== -To conveniently test on multiple Python versions, we also provide a ``.tox`` -file. +Once Pelican has been set up for local development, create a topic branch for +your bug fix or feature: + git checkout -b name-of-your-bugfix-or-feature -Building the docs -================= - -If you make changes to the documentation, you should preview your changes -before committing them:: - - $ pip install -r requirements/docs.pip - $ cd docs - $ make html - -Open ``_build/html/index.html`` in your browser to preview the documentation. +Now you can make changes to Pelican, its documentation, and/or other aspects of +the project. Running the test suite -====================== +---------------------- -Each time you add a feature, there are two things to do regarding tests: check -that the existing tests pass, and add tests for the new feature or bugfix. +Each time you make changes to Pelican, there are two things to do regarding +tests: check that the existing tests pass, and add tests for any new features +or bug fixes. The tests are located in ``pelican/tests``, and you can run them +via:: -The tests live in ``pelican/tests`` and you can run them using the -"discover" feature of ``unittest``:: + invoke tests - $ python -Wd -m unittest discover +In addition to running the test suite, the above invocation will also check code +style and let you know whether non-conforming patterns were found. In some cases +these linters will make the needed changes directly, while in other cases you +may need to make additional changes until ``invoke tests`` no longer reports any +code style violations. After making your changes and running the tests, you may see a test failure mentioning that "some generated files differ from the expected functional tests @@ -82,11 +88,11 @@ the nature of your changes, then you should update the output used by the functional tests. To do so, **make sure you have both** ``en_EN.utf8`` **and** ``fr_FR.utf8`` **locales installed**, and then run the following two commands:: - $ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \ + LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \ -s samples/pelican.conf.py samples/content/ - $ LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \ + LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \ -s samples/pelican.conf_FR.py samples/content/ - $ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \ + LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \ samples/content/ You may also find that some tests are skipped because some dependency (e.g., @@ -101,48 +107,68 @@ environments. .. _Tox: https://tox.readthedocs.io/en/latest/ -Python 2/3 compatibility development tips -========================================= +Building the docs +----------------- + +If you make changes to the documentation, you should preview your changes +before committing them:: + + cd docs + make html + +Open ``_build/html/index.html`` in your browser to preview the documentation. + +Plugin development +------------------ + +To create a *new* Pelican plugin, please refer to the `plugin template`_ +repository for detailed instructions. + +If you want to contribute to an *existing* Pelican plugin, follow the steps +above to set up Pelican for local development, and then create a directory to +store cloned plugin repositories:: + + mkdir -p ~/projects/pelican-plugins + +Assuming you wanted to contribute to the Simple Footnotes plugin, you would +first browse to the `Simple Footnotes`_ repository on GitHub and tap the **Fork** +button at top-right. Then clone the source for your fork and add the upstream +project as a Git remote:: + + git clone https://github.com/YOUR_USERNAME/simple-footnotes.git ~/projects/pelican-plugins/simple-footnotes + cd ~/projects/pelican-plugins/simple-footnotes + git remote add upstream https://github.com/pelican-plugins/simple-footnotes.git + +Install the needed dependencies and set up the project:: + + invoke setup -Here are some tips that may be useful for writing code that is compatible with -both Python 2.7 and Python 3: +After writing new tests for your plugin changes, run the plugin test suite:: -- Use new syntax. For example: + invoke tests - - ``print .. -> print(..)`` - - ``except .., e -> except .. as e`` +.. _plugin template: https://github.com/getpelican/cookiecutter-pelican-plugin +.. _Simple Footnotes: https://github.com/pelican-plugins/simple-footnotes -- Use new methods. For example: +Submitting your changes +----------------------- - - ``dict.iteritems() -> dict.items()`` - - ``xrange(..) - > list(range(..))`` +Assuming linting validation and tests pass, add a ``RELEASE.md`` file in the root +of the project that contains the release type (major, minor, patch) and a +summary of the changes that will be used as the release changelog entry. +For example:: -- Use ``six`` where necessary. For example: + Release type: patch - - ``isinstance(.., basestring) -> isinstance(.., six.string_types)`` - - ``isinstance(.., unicode) -> isinstance(.., six.text_type)`` + Fix browser reloading upon changes to content, settings, or theme -- Assume every string and literal is Unicode: +Commit your changes and push your topic branch:: - - Use ``from __future__ import unicode_literals`` - - Do not use the prefix ``u'`` before strings. - - Do not encode/decode strings in the middle of something. Follow the code to - the source/target of a string and encode/decode at the first/last possible - point. - - In particular, write your functions to expect and to return Unicode. - - Encode/decode strings if the string is the output of a Python function that - is known to handle this badly. For example, ``strftime()`` in Python 2. - - Do not use the magic method ``__unicode()__`` in new classes. Use only - ``__str()__`` and decorate the class with ``@python_2_unicode_compatible``. + git add . + git commit -m "Your detailed description of your changes" + git push origin name-of-your-bugfix-or-feature -- ``setlocale()`` in Python 2 fails when we give the locale name as Unicode, - and since we are using ``from __future__ import unicode_literals``, we do - that everywhere! As a workaround, enclose the locale name with ``str()``; - in Python 2 this casts the name to a byte string, while in Python 3 this - should do nothing, because the locale name was already Unicode. -- Do not start integer literals with a zero. This is a syntax error in Python 3. -- Unfortunately there seems to be no octal notation that is valid in both - Python 2 and 3. Use decimal notation instead. +Finally, browse to your repository fork on GitHub and submit a pull request. Logging tips @@ -160,8 +186,8 @@ For logging messages that are not repeated, use the usual Python way:: logger.warning("A warning with %s formatting", arg_to_be_formatted) Do not format log messages yourself. Use ``%s`` formatting in messages and pass -arguments to logger. This is important, because Pelican logger will preprocess -some arguments (like Exceptions) for Py2/Py3 compatibility. +arguments to logger. This is important, because the Pelican logger will +preprocess some arguments, such as exceptions. Limiting extraneous log messages -------------------------------- |