Thank you for contributing to Pinax!
There are many ways to contribute: reporting bugs, requesting features, providing input on issues and pull requests, writing documentation, and submitting code, just to name a few.
Some contributions require a pull request, and others do not.
If you find a bug in a Pinax code base or have a feature request, please open an issue in the repo of that particular Pinax code base.
We also welcome input and discussion in issues and pull requests.
Contributions that will be merged into a code base require a pull request so that a maintainer can review the contribution before merging.
Most people do not have write access to the Pinax organization and will therefore need to fork the Pinax repo they are working on and clone the repo locally.
To fork the repo, click the "Fork" button in the upper right hand corner of the Pinax repo. To clone the repo and change directory, enter your terminal and use the following commands, substituting the real values for the carets and values contained in them.
$ git clone https://github.com/<your_username>/<pinax_repo_name>
$ cd <pinax_repo_name>Depending on the situation, you might or might not need to create a virtual environment. If needed, do so. A virtual environment is generally required when you are installing packages and want to isolate them from the rest of your computer environment.
You should now be in the master branch of the repo. You can check by using the following command:
$ git branchIf you have forked the repo, it's possible to make your change in the master branch of the fork, and submit a request for the master branch of your fork to be merged into the master branch of the Pinax repo. However, many people prefer to create a separate branch. Leaving the master branch unchanged means that you can create multiple branches off of it.
$ git checkout -b <new_branch>Keep in mind, that when you create a new branch, you might need to setup the branch like a new project, including installing packages, even if you have done so in the master branch.
When ready, make your change, preferably including any new unit tests your change requires. Also, for apps included in the most recent release, run tox, if needed. This can usually be done by running the Makefile.
$ MakeAfter any required tests pass and when you are ready, commit your changes. For example:
$ git add .
$ git commit -m "Your commit message"You can then push your change to your forked repo:
$ git push origin <new_branch>You can continue to work on the branch, if needed, by making changes locally, adding and committing the changes, then pushing the changes to your branch in the forked repo.
When you are ready to submit a pull request, go to the original Pinax repo you forked. There should be a message identifying your branch and suggesting that you submit a pull request. Click on the "Compare & pull request" button.
Usually, the base branch should be the Pinax repo's master branch and the compare branch will be the branch you created and pushed to your fork. Double check that this is correct and change it if needed.
Create a pull request title and description.
A box will be checked by default giving Pinax maintainers the ability to edit the pull request. Leave this checked.
Double check your changes
Click "Create pull request"
When writing code to be included in a Pinax app, keep our style in mind:
- Although we do not follow PEP 8 in every case, PEP 8 is an excellent starting point.
- We do strictly follow the Django coding style outlined in the official Django docs.
A few Pinax style choices that diverge from PEP8 and Django's coding style:
- PEP8 tries to keep line length at 80 characters. We follow it when we can, but not when it makes a line harder to read. It is okay to go a little bit over 80 characters if not breaking the line improves readability.
- Use double quotes not single quotes. Single quotes are allowed in cases where a double quote is needed in the string. This makes the code read cleaner in those cases.
- Blank lines should contain no whitespace.
- Docstrings always use three double quotes on a line of their own, so, for example, a single line docstring should take up three lines not one.
- Imports are grouped specifically and ordered alphabetically. This is shown in the example below.
- Always use
reverseand never@models.permalink. - Tuples should be reserved for positional data structures and not used where a list is more appropriate.
- URL patterns should use the
url()function rather than a tuple.
Here is an example of these rules applied:
# first set of imports are stdlib imports
# non-from imports go first then from style import in their own group
import csv
# second set of imports are Django imports
from django.contrib.auth.models import User
from django.db import models
from django.urls import reverse
from django.utils import timezone
from django.utils.translation import ugettext_lazy as _
# third set of imports are external apps (if applicable)
from tagging.fields import TagField
# fourth set of imports are local apps
from .fields import MarkupField
class Task(models.Model):
"""
A model for storing a task.
"""
creator = models.ForeignKey(User)
created = models.DateTimeField(default=timezone.now)
modified = models.DateTimeField(default=timezone.now)
objects = models.Manager()
class Meta:
verbose_name = _("task")
verbose_name_plural = _("tasks")
def __unicode__(self):
return self.summary
def save(self, **kwargs):
self.modified = datetime.now()
super(Task, self).save(**kwargs)
def get_absolute_url(self):
return reverse("task_detail", kwargs={"task_id": self.pk})
# custom methods
class TaskComment(models.Model):
# ... you get the point ...
pass
Please use atomic commits. In other words, keep your pull requests focused on one specific thing only. If you have a number of contributions to make, please send seperate pull requests. It is much easier on maintainers to receive small, well defined, pull requests, than it is to have a single large one that batches up a lot of unrelated commits.
If you ended up making multiple commits for one logical change, please rebase into a single commit.
$ git rebase -i HEAD~10 # where 10 is the number of commits back you needThis will pop up an editor with your commits and some instructions you want to squash commits down by replacing 'pick' with 's' to have it combined with the commit before it. You can squash multiple ones at the same time.
When you save and exit the text editor where you were squashing commits, git will squash them down and then present you with another editor with commit messages. Choose the one to apply to the squashed commit (or write a new one entirely.) Save and exit will complete the rebase. Use a forced push to your fork.
$ git push -fWriting a good commit message makes it simple for us to identify what your commit does from a high-level. There are some basic guidelines we'd like to ask you to follow.
A critical part is that you keep the first line as short and sweet as possible. This line is important because when git shows commits and it has limited space or a different formatting option is used the first line becomes all someone might see. If your change isn't something non-trivial or there reasoning behind the change is not obvious, then please write up an extended message explaining the fix, your rationale, and anything else relevant for someone else that might be reviewing the change. Lastly, if there is a corresponding issue in Github issues for it, use the final line to provide a message that will link the commit message to the issue and auto-close it if appropriate.
Add ability to travel back in time
You need to be driving 88 miles per hour to generate 1.21 gigawatts of
power to properly use this feature.
Fixes #88