encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-11-14 05:36:50 +03:00
Code Issues Packages Projects Releases Wiki Activity
gh-pages
django-rest-framework/community/contributing/index.html
Tom Christie 2c8d1f13db Deployed c7a7eae5 with MkDocs version: 1.6.0
2024-06-14 16:49:25 +01:00

681 lines
31 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Contributing to REST framework - Django REST framework</title>
<link href="../../img/favicon.ico" rel="icon" type="image/x-icon">
<link rel="canonical" href="https://www.django-rest-framework.org/community/contributing/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, Contributing to REST framework">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
<link href="../../css/prettify.css" rel="stylesheet">
<link href="../../css/bootstrap.css" rel="stylesheet">
<link href="../../css/bootstrap-responsive.css" rel="stylesheet">
<link href="../../css/default.css" rel="stylesheet">
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-18852272-2']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script');
ga.type = 'text/javascript';
ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
})();
</script>
<style>
#sidebarInclude img {
margin-bottom: 10px;
}
#sidebarInclude a.promo {
color: black;
}
@media (max-width: 767px) {
div.promo {
display: none;
}
}
</style>
</head>
<body onload="prettyPrint()" class="-page">
<div class="wrapper">
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-inner">
<div class="container-fluid">
<a class="repo-link btn btn-primary btn-small" href="https://github.com/encode/django-rest-framework/tree/master">GitHub</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../project-management/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../third-party-packages/">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a id="search_modal_show" class="repo-link btn btn-inverse btn-small" href="#mkdocs_search_modal" data-toggle="modal" data-target="#mkdocs_search_modal"><i class="icon-search icon-white"></i> Search</a>
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="https://www.django-rest-framework.org/">Django REST framework</a>
<div class="nav-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li >
<a href="../..">Home</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../../tutorial/quickstart/">Quickstart</a>
</li>
<li >
<a href="../../tutorial/1-serialization/">1 - Serialization</a>
</li>
<li >
<a href="../../tutorial/2-requests-and-responses/">2 - Requests and responses</a>
</li>
<li >
<a href="../../tutorial/3-class-based-views/">3 - Class based views</a>
</li>
<li >
<a href="../../tutorial/4-authentication-and-permissions/">4 - Authentication and permissions</a>
</li>
<li >
<a href="../../tutorial/5-relationships-and-hyperlinked-apis/">5 - Relationships and hyperlinked APIs</a>
</li>
<li >
<a href="../../tutorial/6-viewsets-and-routers/">6 - Viewsets and routers</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../../api-guide/requests/">Requests</a>
</li>
<li >
<a href="../../api-guide/responses/">Responses</a>
</li>
<li >
<a href="../../api-guide/views/">Views</a>
</li>
<li >
<a href="../../api-guide/generic-views/">Generic views</a>
</li>
<li >
<a href="../../api-guide/viewsets/">Viewsets</a>
</li>
<li >
<a href="../../api-guide/routers/">Routers</a>
</li>
<li >
<a href="../../api-guide/parsers/">Parsers</a>
</li>
<li >
<a href="../../api-guide/renderers/">Renderers</a>
</li>
<li >
<a href="../../api-guide/serializers/">Serializers</a>
</li>
<li >
<a href="../../api-guide/fields/">Serializer fields</a>
</li>
<li >
<a href="../../api-guide/relations/">Serializer relations</a>
</li>
<li >
<a href="../../api-guide/validators/">Validators</a>
</li>
<li >
<a href="../../api-guide/authentication/">Authentication</a>
</li>
<li >
<a href="../../api-guide/permissions/">Permissions</a>
</li>
<li >
<a href="../../api-guide/caching/">Caching</a>
</li>
<li >
<a href="../../api-guide/throttling/">Throttling</a>
</li>
<li >
<a href="../../api-guide/filtering/">Filtering</a>
</li>
<li >
<a href="../../api-guide/pagination/">Pagination</a>
</li>
<li >
<a href="../../api-guide/versioning/">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation/">Content negotiation</a>
</li>
<li >
<a href="../../api-guide/metadata/">Metadata</a>
</li>
<li >
<a href="../../api-guide/schemas/">Schemas</a>
</li>
<li >
<a href="../../api-guide/format-suffixes/">Format suffixes</a>
</li>
<li >
<a href="../../api-guide/reverse/">Returning URLs</a>
</li>
<li >
<a href="../../api-guide/exceptions/">Exceptions</a>
</li>
<li >
<a href="../../api-guide/status-codes/">Status codes</a>
</li>
<li >
<a href="../../api-guide/testing/">Testing</a>
</li>
<li >
<a href="../../api-guide/settings/">Settings</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../../topics/documenting-your-api/">Documenting your API</a>
</li>
<li >
<a href="../../topics/internationalization/">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
<li >
<a href="../../topics/browsable-api/">The Browsable API</a>
</li>
<li >
<a href="../../topics/rest-hypermedia-hateoas/">REST, Hypermedia & HATEOAS</a>
</li>
</ul>
</li>
<li class="dropdown active">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Community <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../tutorials-and-resources/">Tutorials and Resources</a>
</li>
<li >
<a href="../third-party-packages/">Third Party Packages</a>
</li>
<li class="active" >
<a href="./">Contributing to REST framework</a>
</li>
<li >
<a href="../project-management/">Project management</a>
</li>
<li >
<a href="../release-notes/">Release Notes</a>
</li>
<li >
<a href="../3.15-announcement/">3.15 Announcement</a>
</li>
<li >
<a href="../3.14-announcement/">3.14 Announcement</a>
</li>
<li >
<a href="../3.13-announcement/">3.13 Announcement</a>
</li>
<li >
<a href="../3.12-announcement/">3.12 Announcement</a>
</li>
<li >
<a href="../3.11-announcement/">3.11 Announcement</a>
</li>
<li >
<a href="../3.10-announcement/">3.10 Announcement</a>
</li>
<li >
<a href="../3.9-announcement/">3.9 Announcement</a>
</li>
<li >
<a href="../3.8-announcement/">3.8 Announcement</a>
</li>
<li >
<a href="../3.7-announcement/">3.7 Announcement</a>
</li>
<li >
<a href="../3.6-announcement/">3.6 Announcement</a>
</li>
<li >
<a href="../3.5-announcement/">3.5 Announcement</a>
</li>
<li >
<a href="../3.4-announcement/">3.4 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.1-announcement/">3.1 Announcement</a>
</li>
<li >
<a href="../3.0-announcement/">3.0 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
<li >
<a href="../mozilla-grant/">Mozilla Grant</a>
</li>
<li >
<a href="../funding/">Funding</a>
</li>
<li >
<a href="../jobs/">Jobs</a>
</li>
</ul>
</li>
</ul>
</div>
<!--/.nav-collapse -->
</div>
</div>
</div>
<div class="body-content">
<div class="container-fluid">
<!-- Search Modal -->
<div id="mkdocs_search_modal" class="modal hide fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
<h3 id="myModalLabel">Documentation search</h3>
</div>
<div class="modal-body">
<form role="form" autocomplete="off">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search..." id="mkdocs-search-query">
</div>
</form>
<div id="mkdocs-search-results"></div>
</div>
<div class="modal-footer">
<button class="btn" data-dismiss="modal" aria-hidden="true">Close</button>
</div>
</div>
<div class="row-fluid">
<div class="span3">
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main">
<a href="#contributing-to-rest-framework">Contributing to REST framework</a>
</li>
<li>
<a href="#community">Community</a>
</li>
<li>
<a href="#code-of-conduct">Code of conduct</a>
</li>
<li class="main">
<a href="#issues">Issues</a>
</li>
<li>
<a href="#triaging-issues">Triaging issues</a>
</li>
<li class="main">
<a href="#development">Development</a>
</li>
<li>
<a href="#testing">Testing</a>
</li>
<li>
<a href="#pull-requests">Pull requests</a>
</li>
<li>
<a href="#managing-compatibility-issues">Managing compatibility issues</a>
</li>
<li class="main">
<a href="#documentation">Documentation</a>
</li>
<li>
<a href="#building-the-documentation">Building the documentation</a>
</li>
<li>
<a href="#language-style">Language style</a>
</li>
<li>
<a href="#markdown-style">Markdown style</a>
</li>
<div class="promo">
<hr/>
<div id="sidebarInclude">
</div>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<h1 id="contributing-to-rest-framework"><a class="toclink" href="#contributing-to-rest-framework">Contributing to REST framework</a></h1>
<blockquote>
<p>The world can only really be changed one piece at a time. The art is picking that piece.</p>
<p>&mdash; <a href="https://www.w3.org/People/Berners-Lee/FAQ.html">Tim Berners-Lee</a></p>
</blockquote>
<p>There are many ways you can contribute to Django REST framework. We'd like it to be a community-led project, so please get involved and help shape the future of the project.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>At this point in its lifespan we consider Django REST framework to be feature-complete. We focus on pull requests that track the continued development of Django versions, and generally do not accept new features or code formatting changes.</p>
</div>
<h2 id="community"><a class="toclink" href="#community">Community</a></h2>
<p>The most important thing you can do to help push the REST framework project forward is to be actively involved wherever possible. Code contributions are often overvalued as being the primary way to get involved in a project, we don't believe that needs to be the case.</p>
<p>If you use REST framework, we'd love you to be vocal about your experiences with it - you might consider writing a blog post about using REST framework, or publishing a tutorial about building a project with a particular JavaScript framework. Experiences from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are more difficult to understand and work with.</p>
<p>Other really great ways you can help move the community forward include helping to answer questions on the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">discussion group</a>, or setting up an <a href="https://stackexchange.com/filters/66475/rest-framework">email alert on StackOverflow</a> so that you get notified of any new questions with the <code>django-rest-framework</code> tag.</p>
<p>When answering questions make sure to help future contributors find their way around by hyperlinking wherever possible to related threads and tickets, and include backlinks from those items if relevant.</p>
<h2 id="code-of-conduct"><a class="toclink" href="#code-of-conduct">Code of conduct</a></h2>
<p>Please keep the tone polite &amp; professional. For some users a discussion on the REST framework mailing list or ticket tracker may be their first engagement with the open source community. First impressions count, so let's try to make everyone feel welcome.</p>
<p>Be mindful in the language you choose. As an example, in an environment that is heavily male-dominated, posts that start 'Hey guys,' can come across as unintentionally exclusive. It's just as easy, and more inclusive to use gender neutral language in those situations.</p>
<p>The <a href="https://www.djangoproject.com/conduct/">Django code of conduct</a> gives a fuller set of guidelines for participating in community forums.</p>
<h1 id="issues"><a class="toclink" href="#issues">Issues</a></h1>
<p>Our contribution process is that the <a href="https://github.com/encode/django-rest-framework/discussions">GitHub discussions page</a> should generally be your starting point. Please only raise an issue or pull request if you've been recommended to do so after discussion.</p>
<p>Some tips on good potential issue reporting:</p>
<ul>
<li>Django REST framework is considered feature-complete. Please do not file requests to change behavior, unless it is required for security reasons or to maintain compatibility with upcoming Django or Python versions.</li>
<li>Search the GitHub project page for related items, and make sure you're running the latest version of REST framework before reporting an issue.</li>
<li>Feature requests will typically be closed with a recommendation that they be implemented outside the core REST framework library (e.g. as third-party libraries). This approach allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability and great documentation.</li>
</ul>
<h2 id="triaging-issues"><a class="toclink" href="#triaging-issues">Triaging issues</a></h2>
<p>Getting involved in triaging incoming issues is a good way to start contributing. Every single ticket that comes into the ticket tracker needs to be reviewed in order to determine what the next steps should be. Anyone can help out with this, you just need to be willing to</p>
<ul>
<li>Read through the ticket - does it make sense, is it missing any context that would help explain it better?</li>
<li>Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group?</li>
<li>If the ticket is a bug report, can you reproduce it? Are you able to write a failing test case that demonstrates the issue and that can be submitted as a pull request?</li>
<li>If the ticket is a feature request, could the feature request instead be implemented as a third party package?</li>
<li>If a ticket hasn't had much activity and addresses something you need, then comment on the ticket and try to find out what's needed to get it moving again.</li>
</ul>
<h1 id="development"><a class="toclink" href="#development">Development</a></h1>
<p>To start developing on Django REST framework, first create a Fork from the
<a href="https://github.com/encode/django-rest-framework">Django REST Framework repo</a> on GitHub.</p>
<p>Then clone your fork. The clone command will look like this, with your GitHub
username instead of YOUR-USERNAME:</p>
<pre><code>git clone https://github.com/YOUR-USERNAME/django-rest-framework
</code></pre>
<p>See GitHub's <a href="https://help.github.com/articles/fork-a-repo/"><em>Fork a Repo</em></a> Guide for more help.</p>
<p>Changes should broadly follow the <a href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a> style conventions, and we recommend you set up your editor to automatically indicate non-conforming styles.
You can check your contributions against these conventions each time you commit using the <a href="https://pre-commit.com/">pre-commit</a> hooks, which we also run on CI.
To set them up, first ensure you have the pre-commit tool installed, for example:</p>
<pre><code>python -m pip install pre-commit
</code></pre>
<p>Then run:</p>
<pre><code>pre-commit install
</code></pre>
<h2 id="testing"><a class="toclink" href="#testing">Testing</a></h2>
<p>To run the tests, clone the repository, and then:</p>
<pre><code># Setup the virtual environment
python3 -m venv env
source env/bin/activate
pip install -e .
pip install -r requirements.txt
# Run the tests
./runtests.py
</code></pre>
<h3 id="test-options"><a class="toclink" href="#test-options">Test options</a></h3>
<p>Run using a more concise output style.</p>
<pre><code>./runtests.py -q
</code></pre>
<p>Run the tests for a given test case.</p>
<pre><code>./runtests.py MyTestCase
</code></pre>
<p>Run the tests for a given test method.</p>
<pre><code>./runtests.py MyTestCase.test_this_method
</code></pre>
<p>Shorter form to run the tests for a given test method.</p>
<pre><code>./runtests.py test_this_method
</code></pre>
<p>Note: The test case and test method matching is fuzzy and will sometimes run other tests that contain a partial string match to the given command line input.</p>
<h3 id="running-against-multiple-environments"><a class="toclink" href="#running-against-multiple-environments">Running against multiple environments</a></h3>
<p>You can also use the excellent <a href="https://tox.readthedocs.io/en/latest/">tox</a> testing tool to run the tests against all supported versions of Python and Django. Install <code>tox</code> globally, and then simply run:</p>
<pre><code>tox
</code></pre>
<h2 id="pull-requests"><a class="toclink" href="#pull-requests">Pull requests</a></h2>
<p>It's a good idea to make pull requests early on. A pull request represents the start of a discussion, and doesn't necessarily need to be the final, finished submission.</p>
<p>It's also always best to make a new branch before starting work on a pull request. This means that you'll be able to later switch back to working on another separate issue without interfering with an ongoing pull requests.</p>
<p>It's also useful to remember that if you have an outstanding pull request then pushing new commits to your GitHub repo will also automatically update the pull requests.</p>
<p>GitHub's documentation for working on pull requests is <a href="https://help.github.com/articles/using-pull-requests">available here</a>.</p>
<p>Always run the tests before submitting pull requests, and ideally run <code>tox</code> in order to check that your modifications are compatible on all supported versions of Python and Django.</p>
<p>Once you've made a pull request take a look at the build status in the GitHub interface and make sure the tests are running as you'd expect.</p>
<p><img alt="Build status" src="../../img/build-status.png" /></p>
<p><em>Above: build notifications</em></p>
<h2 id="managing-compatibility-issues"><a class="toclink" href="#managing-compatibility-issues">Managing compatibility issues</a></h2>
<p>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 the <code>compat.py</code> module, and should provide a single common interface that the rest of the codebase can use.</p>
<h1 id="documentation"><a class="toclink" href="#documentation">Documentation</a></h1>
<p>The documentation for REST framework is built from the <a href="https://daringfireball.net/projects/markdown/basics">Markdown</a> source files in <a href="https://github.com/encode/django-rest-framework/tree/master/docs">the docs directory</a>.</p>
<p>There are many great Markdown editors that make working with the documentation really easy. The <a href="http://mouapp.com/">Mou editor for Mac</a> is one such editor that comes highly recommended.</p>
<h2 id="building-the-documentation"><a class="toclink" href="#building-the-documentation">Building the documentation</a></h2>
<p>To build the documentation, install MkDocs with <code>pip install mkdocs</code> and then run the following command.</p>
<pre><code>mkdocs build
</code></pre>
<p>This will build the documentation into the <code>site</code> directory.</p>
<p>You can build the documentation and open a preview in a browser window by using the <code>serve</code> command.</p>
<pre><code>mkdocs serve
</code></pre>
<h2 id="language-style"><a class="toclink" href="#language-style">Language style</a></h2>
<p>Documentation should be in American English. The tone of the documentation is very important - try to stick to a simple, plain, objective and well-balanced style where possible.</p>
<p>Some other tips:</p>
<ul>
<li>Keep paragraphs reasonably short.</li>
<li>Don't use abbreviations such as 'e.g.' but instead use the long form, such as 'For example'.</li>
</ul>
<h2 id="markdown-style"><a class="toclink" href="#markdown-style">Markdown style</a></h2>
<p>There are a couple of conventions you should follow when working on the documentation.</p>
<h5 id="1-headers"><a class="toclink" href="#1-headers">1. Headers</a></h5>
<p>Headers should use the hash style. For example:</p>
<pre><code>### Some important topic
</code></pre>
<p>The underline style should not be used. <strong>Don't do this:</strong></p>
<pre><code>Some important topic
====================
</code></pre>
<h5 id="2-links"><a class="toclink" href="#2-links">2. Links</a></h5>
<p>Links should always use the reference style, with the referenced hyperlinks kept at the end of the document.</p>
<pre><code>Here is a link to [some other thing][other-thing].
More text...
[other-thing]: http://example.com/other/thing
</code></pre>
<p>This style helps keep the documentation source consistent and readable.</p>
<p>If you are hyperlinking to another REST framework document, you should use a relative link, and link to the <code>.md</code> suffix. For example:</p>
<pre><code>[authentication]: ../api-guide/authentication.md
</code></pre>
<p>Linking in this style means you'll be able to click the hyperlink in your Markdown editor to open the referenced document. When the documentation is built, these links will be converted into regular links to HTML pages.</p>
<h5 id="3-notes"><a class="toclink" href="#3-notes">3. Notes</a></h5>
<p>If you want to draw attention to a note or warning, use a pair of enclosing lines, like so:</p>
<pre><code>---
**Note:** A useful documentation note.
---
</code></pre>
</div> <!--/span-->
</div> <!--/row-->
</div> <!--/.fluid-container-->
</div> <!--/.body content-->
<div id="push"></div>
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script async src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
<script src="../../js/jquery-1.8.1-min.js"></script>
<script src="../../js/prettify-1.0.js"></script>
<script src="../../js/bootstrap-2.1.1-min.js"></script>
<script src="../../js/theme.js"></script>
<script>var base_url = '../..';</script>
<script src="../../search/main.js" defer></script>
<script>
var shiftWindow = function() {
scrollBy(0, -50)
};
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
$('.dropdown-menu').on('click touchstart', function(event) {
event.stopPropagation();
});
// Dynamically force sidenav/dropdown to no higher than browser window
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
$(function() {
$(window).resize(function() {
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
});
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink