Skip to content

Remove link to third party cookiecutter template #7902

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.

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
Apr 5, 2021
Merged
Changes from all commits
Commits
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
137 changes: 2 additions & 135 deletions docs/community/third-party-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,142 +14,9 @@ We aim to make creating third party packages as easy as possible, whilst keeping

If you have an idea for a new feature please consider how it may be packaged as a Third Party Package. We're always happy to discuss ideas on the [Mailing List][discussion-group].

## How to create a Third Party Package
## Creating a Third Party Package

### Creating your package

You can use [this cookiecutter template][cookiecutter] for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution.

Note: Let us know if you have an alternate cookiecutter package so we can also link to it.

#### Running the initial cookiecutter command

To run the initial cookiecutter command, you'll first need to install the Python `cookiecutter` package.

$ pip install cookiecutter

Once `cookiecutter` is installed just run the following to create a new project.

$ cookiecutter gh:jpadilla/cookiecutter-django-rest-framework

You'll be prompted for some questions, answer them, then it'll create your Python package in the current working directory based on those values.

full_name (default is "Your full name here")? Johnny Appleseed
email (default is "[email protected]")? [email protected]
github_username (default is "yourname")? jappleseed
pypi_project_name (default is "dj-package")? djangorestframework-custom-auth
repo_name (default is "dj-package")? django-rest-framework-custom-auth
app_name (default is "djpackage")? custom_auth
project_short_description (default is "Your project description goes here")?
year (default is "2014")?
version (default is "0.1.0")?

#### Getting it onto GitHub

To put your project up on GitHub, you'll need a repository for it to live in. You can create a new repository [here][new-repo]. If you need help, check out the [Create A Repo][create-a-repo] article on GitHub.


#### Adding to Travis CI

We recommend using [Travis CI][travis-ci], a hosted continuous integration service which integrates well with GitHub and is free for public repositories.

To get started with Travis CI, [sign in][travis-ci] with your GitHub account. Once you're signed in, go to your [profile page][travis-profile] and enable the service hook for the repository you want.

If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests. By default, builds are triggered every time you push to your repository or create Pull Request.

#### Uploading to PyPI

Once you've got at least a prototype working and tests running, you should publish it on PyPI to allow others to install it via `pip`.

You must [register][pypi-register] an account before publishing to PyPI.

To register your package on PyPI run the following command.

$ python setup.py register

If this is the first time publishing to PyPI, you'll be prompted to login.

Note: Before publishing you'll need to make sure you have the latest pip that supports `wheel` as well as install the `wheel` package.

$ pip install --upgrade pip
$ pip install wheel

After this, every time you want to release a new version on PyPI just run the following command.

$ python setup.py publish
You probably want to also tag the version now:
git tag -a {0} -m 'version 0.1.0'
git push --tags

After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release.

We recommend to follow [Semantic Versioning][semver] for your package's versions.

### Development

#### Version requirements

The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, `tox.ini`, `.travis.yml`, and `setup.py` to match the set of versions you wish to support.

#### Tests

The cookiecutter template includes a `runtests.py` which uses the `pytest` package as a test runner.

Before running, you'll need to install a couple test requirements.

$ pip install -r requirements.txt

Once requirements installed, you can run `runtests.py`.

$ ./runtests.py

Run using a more concise output style.

$ ./runtests.py -q

Run the tests using a more concise output style, no coverage, no flake8.

$ ./runtests.py --fast

Don't run the flake8 code linting.

$ ./runtests.py --nolint

Only run the flake8 code linting, don't run the tests.

$ ./runtests.py --lintonly

Run the tests for a given test case.

$ ./runtests.py MyTestCase

Run the tests for a given test method.

$ ./runtests.py MyTestCase.test_this_method

Shorter form to run the tests for a given test method.

$ ./runtests.py test_this_method

To run your tests against multiple versions of Python as different versions of requirements such as Django we recommend using `tox`. [Tox][tox-docs] is a generic virtualenv management and test command line tool.

First, install `tox` globally.

$ pip install tox

To run `tox`, just simply run:

$ tox

To run a particular `tox` environment:

$ tox -e envlist

`envlist` is a comma-separated value to that specifies the environments to run tests against. To view a list of all possible test environments, run:

$ tox -l

#### Version compatibility
### Version compatibility

Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into a `compat.py` module, and should provide a single common interface that the rest of the codebase can use.

Expand Down