Skip to content

Doc: Move sample workflow out of the main document #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 11, 2017
Merged

Doc: Move sample workflow out of the main document #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 9 additions & 82 deletions Doc/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@ If you'd like to contribute (be it code, documentation, maintenance effort,
or anything else), this guide is for you.


.. toctree::
:hidden:

sample_workflow.rst


Communication
=============

Expand Down Expand Up @@ -54,8 +60,8 @@ If required, write to coordinate a more secure channel.
All other communication should be public.


Process for Code contributions
==============================
Contributing code
=================

If you're used to open-source Python development with Git, here's the gist:

Expand All @@ -76,86 +82,7 @@ Or, if you prefer to avoid closed-source services:
.. _Read the Docs: http://python-ldap.readthedocs.io/

If you're new to some aspect of the project, you're welcome to use (or adapt)
the workflow below.


Sample workflow
---------------

We assume that, as a user of python-ldap you're not new to software
development in general, so these instructions are terse.
If you need additional detail, please do ask on the mailing list.

.. note::

The following instructions are for Linux.
If you can translate them to another system, please contribute your
translation!


Install `Git`_ and `tox`_.

Clone the repository::

$ git clone https://github.com/python-ldap/python-ldap
$ cd python-ldap

Create a `virtual environment`_ to ensure you in-development python-ldap won't
affect the rest of your system::

$ python3 -m venv __venv__

(For Python 2, install `virtualenv`_ and use it instead of ``python3 -m venv``.)

.. _git: https://git-scm.com/
.. _virtual environment: https://docs.python.org/3/library/venv.html
.. _virtualenv: https://virtualenv.pypa.io/en/stable/

Activate the virtual environment::

$ source __venv__/bin/activate

Install python-ldap to it in `editable mode`_::

(__venv__)$ python -m pip install -e .

This way, importing a Python module from python-ldap will directly
use the code from your source tree.
If you change C code, you will still need to recompile
(using the ``pip install`` command again).

.. _editable mode: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs

Change the code as desired.


To run tests, install and run `tox`_::

(__venv__)$ python -m pip install tox
(__venv__)$ tox --skip-missing-interpreters

This will run tests on all supported versions of Python that you have
installed, skipping the ones you don't.
To run a subset of test environments, run for example::

(__venv__)$ tox -e py27,py36

In addition to ``pyXY`` environments, we have extra environments
for checking things independent of the Python version:

* ``doc`` checks syntax and spelling of the documentation
* ``coverage-report`` generates a test coverage report for Python code.
It must be used last, e.g. ``tox -e py27,py36,coverage-report``.
* ``py2-nosasltls`` and ``py3-nosasltls`` check functionality without
SASL and TLS bindings compiled in.


When your change is ready, commit to Git, and submit a pull request on GitHub.
You can take a look at the `committer instructions`_ to see what we are looking
for in a pull request.

If you don't want to open a GitHub account, please send patches as attachments
to the python-ldap mailing list.
our :ref:`sample workflow <sample workflow>`.


.. _additional tests:
Expand Down
85 changes: 85 additions & 0 deletions Doc/sample_workflow.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@

.. _sample workflow:

Sample workflow for python-ldap development
-------------------------------------------

This document will guide you through the process of contributing a change
to python-ldap.

We assume that, as a user of python-ldap, you're not new to software
development in general, so these instructions are terse.
If you need additional detail, please do ask on the mailing list.

.. note::

The following instructions are for Linux.
If you can translate them to another system, please contribute your
translation!


Install `Git`_, `tox`_ and the :ref:`build prerequisites`.

.. _tox: https://tox.readthedocs.io/en/latest/

Clone the repository::

$ git clone https://github.com/python-ldap/python-ldap
$ cd python-ldap

Create a `virtual environment`_ to ensure you in-development python-ldap won't
affect the rest of your system::

$ python3 -m venv __venv__

(For Python 2, install `virtualenv`_ and use it instead of ``python3 -m venv``.)

.. _git: https://git-scm.com/
.. _virtual environment: https://docs.python.org/3/library/venv.html
.. _virtualenv: https://virtualenv.pypa.io/en/stable/

Activate the virtual environment::

$ source __venv__/bin/activate

Install python-ldap to it in `editable mode`_::

(__venv__)$ python -m pip install -e .

This way, importing a Python module from python-ldap will directly
use the code from your source tree.
If you change C code, you will still need to recompile
(using the ``pip install`` command again).

.. _editable mode: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs

Change the code as desired.


To run tests, install and run `tox`_::

(__venv__)$ python -m pip install tox
(__venv__)$ tox --skip-missing-interpreters

This will run tests on all supported versions of Python that you have
installed, skipping the ones you don't.
To run a subset of test environments, run for example::

(__venv__)$ tox -e py27,py36

In addition to ``pyXY`` environments, we have extra environments
for checking things independent of the Python version:

* ``doc`` checks syntax and spelling of the documentation
* ``coverage-report`` generates a test coverage report for Python code.
It must be used last, e.g. ``tox -e py27,py36,coverage-report``.
* ``py2-nosasltls`` and ``py3-nosasltls`` check functionality without
SASL and TLS bindings compiled in.


When your change is ready, commit to Git, and submit a pull request on GitHub.
You can take a look at the :ref:`committer instructions` to see what we are looking
for in a pull request.

If you don't want to open a GitHub account, please send patches as attachments
to the python-ldap mailing list.