<commit_before>.. _ref-contributing:

Contributing to Pinax
=====================

We are always looking for people wanting to improve Pinax itself. This
document outlines the necessary bits to begin contributing to Pinax.

Getting started
---------------

The Pinax source code is hosted on GitHub_. This means you must have git_
installed locally. We recommend you create an account on GitHub allowing you
to watch and fork the Pinax source code.

You will want to be sure that your git configuration is set for making commits
to a repository. Check the following::

    git config user.name
    git config user.email

If the output of any of the two commands above are not entirely correct you
can easily correct them::

    git config --global user.name "First Last"
    git config --global user.name "<EMAIL>"

It is critical you set this information up correctly. It helps us identify
who you are when you start giving us those awesome patches.

Grabbing the source code
~~~~~~~~~~~~~~~~~~~~~~~~

Once you have forked the Pinax source code you can now make a clone of it to
your local disk. To do this::

    git clone <EMAIL>:<username>/pinax.git

This will create new directory named ``pinax`` which now contains the Pinax
source tree ready for you to get started.

Setting up your environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now that you've cloned the source code you are ready to get your environment
setup to work on Pinax. This section also applies if you are looking to just
run off the latest code. We'll assume that your current working directory is
from within the clone (the ``pinax`` directory)::

    python scripts/pinax-boot.py --development --source=. ../pinax-dev
    source ../pinax-dev/bin/activate

If you use virtualenvwrapper you could alternatively do::

    python scripts/pinax-boot.py --development --source=. $WORKON_HOME/pinax-dev
    workon pinax-development

Finally, you need to install the dependencies for the development version::

    pip install --requirement requirements/external_apps.txt

Committing code
---------------

The great thing about using a distributed versioning control system like git
is that everyone becomes a committer. When other people write good patches
it makes it very easy to include their fixes/features and give them proper
credit for the work.

We recommend that you do all your work on Pinax in a separate branch. When you
are ready to work on a bug or a new feature create yourself a new branch. The
reason why this is important is you can commit as often you like. When you are
ready you can merge in the change. Let's take a look at a common workflow::

    git checkout -b task-1
    ... do work and git commit often ...
    git push origin task-1
    git checkout -b task-1-ready
    git merge --squash --no-commit task-1
    git commit -m "Fixed #1 — added a great new feature"
    git push origin task-1-ready

The reason we have created two new branches is to stay off of ``master``.
Keeping master clean of only upstream changes makes yours and ours lives
easier. You can then send us a pull request for the fix/feature from the
"ready" branch. Then we can easily review it and even take a look at the<commit_msg>Fixed minor bug in contributing documentation<commit_after>.. _ref-contributing:

Contributing to Pinax
=====================

We are always looking for people wanting to improve Pinax itself. This
document outlines the necessary bits to begin contributing to Pinax.

Getting started
---------------

The Pinax source code is hosted on GitHub_. This means you must have git_
installed locally. We recommend you create an account on GitHub allowing you
to watch and fork the Pinax source code.

You will want to be sure that your git configuration is set for making commits
to a repository. Check the following::

    git config user.name
    git config user.email

If the output of any of the two commands above are not entirely correct you
can easily correct them::

    git config --global user.name "First Last"
    git config --global user.name "<EMAIL>"

It is critical you set this information up correctly. It helps us identify
who you are when you start giving us those awesome patches.

Grabbing the source code
~~~~~~~~~~~~~~~~~~~~~~~~

Once you have forked the Pinax source code you can now make a clone of it to
your local disk. To do this::

    git clone <EMAIL>:<username>/pinax.git

This will create new directory named ``pinax`` which now contains the Pinax
source tree ready for you to get started.

Setting up your environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now that you've cloned the source code you are ready to get your environment
setup to work on Pinax. This section also applies if you are looking to just
run off the latest code. We'll assume that your current working directory is
from within the clone (the ``pinax`` directory)::

    python scripts/pinax-boot.py --development --source=. ../pinax-dev
    source ../pinax-dev/bin/activate

If you use virtualenvwrapper you could alternatively do::

    python scripts/pinax-boot.py --development --source=. $WORKON_HOME/pinax-dev
    workon pinax-dev

Finally, you need to install the dependencies for the development version::

    pip install --requirement requirements/external_apps.txt

Committing code
---------------

The great thing about using a distributed versioning control system like git
is that everyone becomes a committer. When other people write good patches
it makes it very easy to include their fixes/features and give them proper
credit for the work.

We recommend that you do all your work on Pinax in a separate branch. When you
are ready to work on a bug or a new feature create yourself a new branch. The
reason why this is important is you can commit as often you like. When you are
ready you can merge in the change. Let's take a look at a common workflow::

    git checkout -b task-1
    ... do work and git commit often ...
    git push origin task-1
    git checkout -b task-1-ready
    git merge --squash --no-commit task-1
    git commit -m "Fixed #1 — added a great new feature"
    git push origin task-1-ready

The reason we have created two new branches is to stay off of ``master``.
Keeping master clean of only upstream changes makes yours and ours lives
easier. You can then send us a pull request for the fix/feature from the
"ready" branch. Then we can easily review it and even take a look at the
{'fraction_non_alphanumeric': 0.07742741180143616, 'fraction_numerical': 0.0018732438339057135, 'mean_word_length': 3.5375354107648724, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5134171', 'n_tokens_mistral': 1635, 'n_tokens_neox': 1555, 'n_words': 972}