1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
|
<!DOCTYPE html>
<html lang="en">
<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Django REST framework - Contributing to REST framework</title>
<link href="http://django-rest-framework.org/img/favicon.ico" rel="icon" type="image/x-icon">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, Contributing to REST framework, Community, Issues, Development, Testing, Documentation, Third party packages, Core committers">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
<link href="http://django-rest-framework.org/css/prettify.css" rel="stylesheet">
<link href="http://django-rest-framework.org/css/bootstrap.css" rel="stylesheet">
<link href="http://django-rest-framework.org/css/bootstrap-responsive.css" rel="stylesheet">
<link href="http://django-rest-framework.org/css/default.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<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>
</head>
<body onload="prettyPrint()" class="contributing-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/tomchristie/django-rest-framework/tree/master">GitHub</a>
<a class="repo-link btn btn-inverse btn-small " href="../topics/rest-framework-2-announcement.html">Next <i class="icon-arrow-right icon-white"></i></a>
<a class="repo-link btn btn-inverse btn-small " href="../topics/rest-hypermedia-hateoas.html"><i class="icon-arrow-left icon-white"></i> Previous</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="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="http://django-rest-framework.org">Django REST framework</a>
<div class="nav-collapse collapse">
<ul class="nav">
<li><a href="http://django-rest-framework.org">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="http://django-rest-framework.org/tutorial/quickstart.html">Quickstart</a></li>
<li><a href="http://django-rest-framework.org/tutorial/1-serialization.html">1 - Serialization</a></li>
<li><a href="http://django-rest-framework.org/tutorial/2-requests-and-responses.html">2 - Requests and responses</a></li>
<li><a href="http://django-rest-framework.org/tutorial/3-class-based-views.html">3 - Class based views</a></li>
<li><a href="http://django-rest-framework.org/tutorial/4-authentication-and-permissions.html">4 - Authentication and permissions</a></li>
<li><a href="http://django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis.html">5 - Relationships and hyperlinked APIs</a></li>
<li><a href="http://django-rest-framework.org/tutorial/6-viewsets-and-routers.html">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="http://django-rest-framework.org/api-guide/requests.html">Requests</a></li>
<li><a href="http://django-rest-framework.org/api-guide/responses.html">Responses</a></li>
<li><a href="http://django-rest-framework.org/api-guide/views.html">Views</a></li>
<li><a href="http://django-rest-framework.org/api-guide/generic-views.html">Generic views</a></li>
<li><a href="http://django-rest-framework.org/api-guide/viewsets.html">Viewsets</a></li>
<li><a href="http://django-rest-framework.org/api-guide/routers.html">Routers</a></li>
<li><a href="http://django-rest-framework.org/api-guide/parsers.html">Parsers</a></li>
<li><a href="http://django-rest-framework.org/api-guide/renderers.html">Renderers</a></li>
<li><a href="http://django-rest-framework.org/api-guide/serializers.html">Serializers</a></li>
<li><a href="http://django-rest-framework.org/api-guide/fields.html">Serializer fields</a></li>
<li><a href="http://django-rest-framework.org/api-guide/relations.html">Serializer relations</a></li>
<li><a href="http://django-rest-framework.org/api-guide/authentication.html">Authentication</a></li>
<li><a href="http://django-rest-framework.org/api-guide/permissions.html">Permissions</a></li>
<li><a href="http://django-rest-framework.org/api-guide/throttling.html">Throttling</a></li>
<li><a href="http://django-rest-framework.org/api-guide/filtering.html">Filtering</a></li>
<li><a href="http://django-rest-framework.org/api-guide/pagination.html">Pagination</a></li>
<li><a href="http://django-rest-framework.org/api-guide/content-negotiation.html">Content negotiation</a></li>
<li><a href="http://django-rest-framework.org/api-guide/format-suffixes.html">Format suffixes</a></li>
<li><a href="http://django-rest-framework.org/api-guide/reverse.html">Returning URLs</a></li>
<li><a href="http://django-rest-framework.org/api-guide/exceptions.html">Exceptions</a></li>
<li><a href="http://django-rest-framework.org/api-guide/status-codes.html">Status codes</a></li>
<li><a href="http://django-rest-framework.org/api-guide/testing.html">Testing</a></li>
<li><a href="http://django-rest-framework.org/api-guide/settings.html">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="http://django-rest-framework.org/topics/documenting-your-api.html">Documenting your API</a></li>
<li><a href="http://django-rest-framework.org/topics/ajax-csrf-cors.html">AJAX, CSRF & CORS</a></li>
<li><a href="http://django-rest-framework.org/topics/browser-enhancements.html">Browser enhancements</a></li>
<li><a href="http://django-rest-framework.org/topics/browsable-api.html">The Browsable API</a></li>
<li><a href="http://django-rest-framework.org/topics/rest-hypermedia-hateoas.html">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://django-rest-framework.org/topics/rest-framework-2-announcement.html">2.0 Announcement</a></li>
<li><a href="http://django-rest-framework.org/topics/2.2-announcement.html">2.2 Announcement</a></li>
<li><a href="http://django-rest-framework.org/topics/2.3-announcement.html">2.3 Announcement</a></li>
<li><a href="http://django-rest-framework.org/topics/release-notes.html">Release Notes</a></li>
<li><a href="http://django-rest-framework.org/topics/credits.html">Credits</a></li>
</ul>
</li>
</ul>
<ul class="nav pull-right">
<!-- TODO
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Version: 2.0.0 <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="#">Trunk</a></li>
<li><a href="#">2.0.0</a></li>
</ul>
</li>
-->
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="body-content">
<div class="container-fluid">
<!-- Search Modal -->
<div id="searchModal" 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">×</button>
<h3 id="myModalLabel">Documentation search</h3>
</div>
<div class="modal-body">
<!-- Custom google search -->
<script>
(function() {
var cx = '015016005043623903336:rxraeohqk6w';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
<gcse:search></gcse:search>
</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">
<!-- TODO
<p style="margin-top: -12px">
<a class="btn btn-mini btn-primary" style="width: 60px">« previous</a>
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next »</a>
</p>
-->
<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 class="main"><a href="#community">Community</a></li>
<li class="main"><a href="#issues">Issues</a></li>
<li class="main"><a href="#development">Development</a></li>
<li class="main"><a href="#testing">Testing</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>
<li class="main"><a href="#third-party-packages">Third party packages</a></li>
<li class="main"><a href="#core-committers">Core committers</a></li>
<div>
<hr>
<p><strong>The team behind REST framework are launching a new API service.</strong></p>
<p>If you want to be first in line when we start issuing invitations, please sign up here:</p>
<!-- Begin MailChimp Signup Form -->
<link href="//cdn-images.mailchimp.com/embedcode/slim-081711.css" rel="stylesheet" type="text/css">
<style type="text/css">
#mc_embed_signup{background:#fff; clear:left; font:14px Helvetica,Arial,sans-serif; }
/* Add your own MailChimp form style overrides in your site stylesheet or in this style block.
We recommend moving this block and the preceding CSS link to the HEAD of your HTML file. */
</style>
<div id="mc_embed_signup" style="background: rgb(245, 245, 245)">
<form action="http://dabapps.us1.list-manage1.com/subscribe/post?u=cf73a9994eb5b8d8d461b5dfb&id=cb6af8e8bd" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate>
<!-- <label for="mce-EMAIL">Keep me posted!</label>
--> <input style="width: 90%" type="email" value="" name="EMAIL" class="email" id="mce-EMAIL" placeholder="email address" required>
<div class="clear"><input class="btn btn-success" type="submit" value="Yes, keep me posted!" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
</form>
</div>
</style></div>
</ul>
<!--End mc_embed_signup-->
</div>
</div>
<div id="main-content" class="span9">
<h1 id="contributing-to-rest-framework">Contributing to REST framework</h1>
<blockquote>
<p>The world can only really be changed one piece at a time. The art is picking that piece.</p>
<p>— <a href="http://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>
<h1 id="community">Community</h1>
<p>If you use and enjoy REST framework please consider <a href="https://github.com/tomchristie/django-rest-framework">staring the project on GitHub</a>, and <a href="https://www.djangopackages.com/grids/g/api/">upvoting it on Django packages</a>. Doing so helps potential new users see that the project is well used, and help us continue to attract new users.</p>
<p>You might also consider writing a blog post on your experience with using REST framework, writing a tutorial about using the project with a particular javascript framework, or simply sharing the love on Twitter.</p>
<p>Other really great ways you can help move the community forward include helping 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="http://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>
<h1 id="issues">Issues</h1>
<p>It's really helpful if you make sure you address issues to the correct channel. Usage questions should be directed to the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">discussion group</a>. Feature requests, bug reports and other issues should be raised on the GitHub <a href="https://github.com/tomchristie/django-rest-framework/issues?state=open">issue tracker</a>.</p>
<p>Some tips on good issue reporting:</p>
<ul>
<li>When describing issues try to phrase your ticket in terms of the <em>behavior</em> you think needs changing rather than the <em>code</em> you think need changing.</li>
<li>Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue.</li>
<li>
<p>If reporting a bug, then try to include a pull request with a failing test case. This will help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one.</p>
</li>
<li>
<p>TODO: Triage</p>
</li>
</ul>
<h1 id="development">Development</h1>
<ul>
<li>git clone & PYTHONPATH</li>
<li>Pep8</li>
<li>Recommend editor that runs pep8</li>
</ul>
<h3 id="pull-requests">Pull requests</h3>
<ul>
<li>Make pull requests early</li>
<li>Describe branching</li>
</ul>
<h3 id="managing-compatibility-issues">Managing compatibility issues</h3>
<ul>
<li>Describe compat module</li>
</ul>
<h1 id="testing">Testing</h1>
<ul>
<li>Running the tests</li>
<li>tox</li>
</ul>
<h1 id="documentation">Documentation</h1>
<p>The documentation for REST framework is built from the <a href="http://daringfireball.net/projects/markdown/basics">Markdown</a> source files in <a href="https://github.com/tomchristie/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">Building the documentation</h2>
<p>To build the documentation, simply run the <code>mkdocs.py</code> script.</p>
<pre class="prettyprint lang-py"><code>./mkdocs.py
</code></pre>
<p>This will build the html output into the <code>html</code> directory.</p>
<p>You can build the documentation and open a preview in a browser window by using the <code>-p</code> flag.</p>
<pre class="prettyprint lang-py"><code>./mkdocs.py -p
</code></pre>
<h2 id="language-style">Language style</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>Use double spacing after the end of sentences.</li>
<li>Don't use the abbreviations such as 'e.g..' but instead use long form, such as 'For example'.</li>
</ul>
<h2 id="markdown-style">Markdown style</h2>
<p>There are a couple of conventions you should follow when working on the documentation.</p>
<h5 id="1-headers">1. Headers</h5>
<p>Headers should use the hash style. For example:</p>
<pre class="prettyprint lang-py"><code>### Some important topic
</code></pre>
<p>The underline style should not be used. <strong>Don't do this:</strong> </p>
<pre class="prettyprint lang-py"><code>Some important topic
====================
</code></pre>
<h5 id="2-links">2. Links</h5>
<p>Links should always use the reference style, with the referenced hyperlinks kept at the end of the document.</p>
<pre class="prettyprint lang-py"><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 class="prettyprint lang-py"><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">3. Notes</h5>
<p>If you want to draw attention to a note or warning, use a pair of enclosing lines, like so:</p>
<pre class="prettyprint lang-py"><code>---
**Note:** Make sure you do this thing.
---
</code></pre>
<h1 id="third-party-packages">Third party packages</h1>
<ul>
<li>Django reusable app</li>
</ul>
<h1 id="core-committers">Core committers</h1>
<ul>
<li>Still use pull reqs</li>
<li>Credits</li>
</ul>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->
</div><!--/.body content-->
<div id="push"></div>
</div><!--/.wrapper -->
<footer class="span12">
<p>Sponsored by <a href="http://dabapps.com/">DabApps</a>.</a></p>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="http://django-rest-framework.org/js/jquery-1.8.1-min.js"></script>
<script src="http://django-rest-framework.org/js/prettify-1.0.js"></script>
<script src="http://django-rest-framework.org/js/bootstrap-2.1.1-min.js"></script>
<script>
//$('.side-nav').scrollspy()
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 to no higher than browser window
$('.side-nav').css('max-height', window.innerHeight - 130);
$(function(){
$(window).resize(function(){
$('.side-nav').css('max-height', window.innerHeight - 130);
});
});
</script>
</body></html>
|
