From de5b9e39dd4c21f4dcceb7cf13c7366b0fb74ec9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 4 Dec 2013 14:59:09 +0000 Subject: First pass on contribution guide --- docs/topics/contributing.md | 91 ++++++++++++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 29 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 123e4a8a..2b18c4f6 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -6,19 +6,27 @@ 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. -# Community +## Community -If you use and enjoy REST framework please consider [staring the project on GitHub][github], and [upvoting it on Django packages][django-packages]. Doing so helps potential new users see that the project is well used, and help us continue to attract new users. +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. -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. +If you use REST framework, we'd love you to be vocal about your experiances with it - you might consider writing a blog post on your experience with using REST framework, or publishing a tutorial about using the project with a particular javascript framework. Experiances from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are and aren't easy to understand and work with. Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. 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. +## Code of conduct + +Please keep the tone polite & 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. + +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. + +The [Django code of conduct][code-of-conduct] gives a fuller set of guidelines for participating in community forums. + # Issues -It's really helpful if you make sure you address issues to the correct channel. Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. +It's really helpful if you can make sure to address issues on the correct channel. Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. Some tips on good issue reporting: @@ -26,30 +34,61 @@ Some tips on good issue reporting: * Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. * 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. +## Triaging issues +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 -* TODO: Triage +* Read through the ticket - does it make sense, is it missing any context that would help explain it better? +* Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group? +* 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? +* If the ticket is a feature request, do you agree with it, and could the feature request instead be implemented as a third party package? # Development +To start developing on Django REST framework, clone the repo: + + git clone git@github.com:tomchristie/django-rest-framework.git + +Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recommend you setup your editor to automatically indicated non-conforming styles. + +## Testing + +To run the tests, clone the repository, and then: + + # Setup the virtual environment + virtualenv env + env/bin/activate + pip install -r requirements.txt + pip install -r optionals.txt + + # Run the tests + rest_framework/runtests/runtests.py -* git clone & PYTHONPATH -* Pep8 -* Recommend editor that runs pep8 +You can also use the excellent `[tox][tox]` testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run: -### Pull requests + tox -* Make pull requests early -* Describe branching +## Pull requests -### Managing compatibility issues +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. -* Describe compat module +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 seperate issue without interfering with an ongoing pull requests. -# Testing +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. -* Running the tests -* tox +GitHub's documentation for working on pull requests is [available here][pull-requests]. + +Always run the tests before submitting pull requests, and ideally run `tox` in order to check that your modifications are compatible with both Python 2 and Python 3, and that they run properly on all supported versions of Django. + +Once you've made a pull request take a look at the travis build status in the GitHub interface and make sure the tests are runnning as you'd expect. + +![Travis status][travis-status] + +*Above: Travis build notifications* + +## Managing compatibility issues + +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 `compat.py` module, and should provide a single common interface that the rest of the codebase can use. # Documentation @@ -77,7 +116,7 @@ Some other tips: * Keep paragraphs reasonably short. * Use double spacing after the end of sentences. -* Don't use the abbreviations such as 'e.g..' but instead use long form, such as 'For example'. +* Don't use the abbreviations such as 'e.g.' but instead use long form, such as 'For example'. ## Markdown style @@ -118,25 +157,19 @@ If you want to draw attention to a note or warning, use a pair of enclosing line --- - **Note:** Make sure you do this thing. + **Note:** A useful documentation note. --- -# Third party packages - -* Django reusable app - -# Core committers - -* Still use pull reqs -* Credits - [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html -[github]: https://github.com/tomchristie/django-rest-framework -[django-packages]: https://www.djangopackages.com/grids/g/api/ +[code-of-conduct]: https://www.djangoproject.com/conduct/ [google-group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [so-filter]: http://stackexchange.com/filters/66475/rest-framework [issues]: https://github.com/tomchristie/django-rest-framework/issues?state=open +[pep-8]: http://www.python.org/dev/peps/pep-0008/ +[travis-status]: ../img/travis-status.png +[pull-requests]: https://help.github.com/articles/using-pull-requests +[tox]: http://tox.readthedocs.org/en/latest/ [markdown]: http://daringfireball.net/projects/markdown/basics [docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ -- cgit v1.2.3 From e80b353085c460c5ab7e9b4d22249f01176c5eb1 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 9 Dec 2013 08:10:51 +0000 Subject: Add notes to contributing docs --- docs/topics/contributing.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 2b18c4f6..4dd2718f 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -33,6 +33,8 @@ Some tips on good issue reporting: * When describing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. * Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. * 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. +* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintainence overhead of REST framework, so that the focus can be on continued stability, bugfixes, and great documentation. +* Closing an issue doesn't necessarily mean the end of a discussion. If you believe your issue has been closed incorrectly, explain why and we'll consider if it needs to be reopened. ## Triaging issues @@ -42,6 +44,7 @@ Getting involved in triaging incoming issues is a good way to start contributing * Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group? * 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? * If the ticket is a feature request, do you agree with it, and could the feature request instead be implemented as a third party package? +* If a ticket hasn't had much activity and it addresses something you need, then comment on the ticket and try to find out what's needed to get it moving again. # Development -- cgit v1.2.3 From 23369650e3502305ebf5d682e141c7d47db89111 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 9 Dec 2013 08:14:21 +0000 Subject: Add notes to contributing docs --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 4dd2718f..b3ab52bb 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -10,7 +10,7 @@ There are many ways you can contribute to Django REST framework. We'd like it t 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. -If you use REST framework, we'd love you to be vocal about your experiances with it - you might consider writing a blog post on your experience with using REST framework, or publishing a tutorial about using the project with a particular javascript framework. Experiances from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are and aren't easy to understand and work with. +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 particularJjavascript 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. Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. -- cgit v1.2.3 From e6f6bb5c7e3e882b0215c981e2f2b6a576820100 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 9 Dec 2013 08:42:09 +0000 Subject: Add notes to contributing docs --- docs/topics/contributing.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index b3ab52bb..77c60fb4 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -164,6 +164,16 @@ If you want to draw attention to a note or warning, use a pair of enclosing line --- +## Third party packages + +New features to REST framework are generally recommended to be implemented as third party libraries that are developed outside of the core framework. Ideally third party libraries should be properly documented and packaged, and made available on PyPI. + +If you have some functionality that you would like to implement as a third party package it's worth contacting the [discussion group][google-group] as others may be willing to get involved. We strongly encourage third party package development and will always try to prioritize time spent helping their development, documentation and packaging. + +Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main documentation. + +We recommend the [`django-reusable-app`][django-reusable-app] template as a good resource for getting up and running with implementing a third party Django package. + [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html [code-of-conduct]: https://www.djangoproject.com/conduct/ [google-group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework @@ -176,3 +186,4 @@ If you want to draw attention to a note or warning, use a pair of enclosing line [markdown]: http://daringfireball.net/projects/markdown/basics [docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ +[django-reusable-app]: https://github.com/dabapps/django-reusable-app -- cgit v1.2.3 From c1be503308e755d72aae2c9695739bd33631e18b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 9 Dec 2013 08:46:18 +0000 Subject: Add notes to contributing docs --- docs/topics/contributing.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 77c60fb4..906950bb 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -164,16 +164,20 @@ If you want to draw attention to a note or warning, use a pair of enclosing line --- -## Third party packages +# Third party packages New features to REST framework are generally recommended to be implemented as third party libraries that are developed outside of the core framework. Ideally third party libraries should be properly documented and packaged, and made available on PyPI. -If you have some functionality that you would like to implement as a third party package it's worth contacting the [discussion group][google-group] as others may be willing to get involved. We strongly encourage third party package development and will always try to prioritize time spent helping their development, documentation and packaging. +## Getting started -Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main documentation. +If you have some functionality that you would like to implement as a third party package it's worth contacting the [discussion group][google-group] as others may be willing to get involved. We strongly encourage third party package development and will always try to prioritize time spent helping their development, documentation and packaging. We recommend the [`django-reusable-app`][django-reusable-app] template as a good resource for getting up and running with implementing a third party Django package. +## Linking to your package + +Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. + [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html [code-of-conduct]: https://www.djangoproject.com/conduct/ [google-group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework -- cgit v1.2.3 From 31dd160256a86c261099602dadb1163811a41e23 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 16 Dec 2013 11:59:14 +0000 Subject: Typo --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 906950bb..30d292f8 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -10,7 +10,7 @@ There are many ways you can contribute to Django REST framework. We'd like it t 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. -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 particularJjavascript 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. +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. Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. -- cgit v1.2.3 From 0cb08ac7076da05bec797144263c472f507958b6 Mon Sep 17 00:00:00 2001 From: amatellanes Date: Wed, 12 Feb 2014 23:17:05 +0100 Subject: Fixed Testing docs section --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 30d292f8..5a5d1a80 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -60,7 +60,7 @@ To run the tests, clone the repository, and then: # Setup the virtual environment virtualenv env - env/bin/activate + source env/bin/activate pip install -r requirements.txt pip install -r optionals.txt -- cgit v1.2.3 From f5f4c1a837f3ead760742bb8d783eaf78ce389e0 Mon Sep 17 00:00:00 2001 From: Kumar McMillan Date: Fri, 28 Feb 2014 16:34:42 -0600 Subject: strip trailing whitespace my editor does this by default --- docs/topics/contributing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 5a5d1a80..0255c484 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -14,7 +14,7 @@ If you use REST framework, we'd love you to be vocal about your experiences with Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. -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. +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. ## Code of conduct @@ -38,7 +38,7 @@ Some tips on good issue reporting: ## Triaging issues -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 +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 * Read through the ticket - does it make sense, is it missing any context that would help explain it better? * Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group? @@ -130,8 +130,8 @@ There are a couple of conventions you should follow when working on the document Headers should use the hash style. For example: ### Some important topic - -The underline style should not be used. **Don't do this:** + +The underline style should not be used. **Don't do this:** Some important topic ==================== @@ -141,9 +141,9 @@ The underline style should not be used. **Don't do this:** Links should always use the reference style, with the referenced hyperlinks kept at the end of the document. Here is a link to [some other thing][other-thing]. - + More text... - + [other-thing]: http://example.com/other/thing This style helps keep the documentation source consistent and readable. @@ -159,9 +159,9 @@ Linking in this style means you'll be able to click the hyperlink in your markdo If you want to draw attention to a note or warning, use a pair of enclosing lines, like so: --- - + **Note:** A useful documentation note. - + --- # Third party packages -- cgit v1.2.3 From e2857bdcffce612814e4cc35bef6f97ce5f39e77 Mon Sep 17 00:00:00 2001 From: Kumar McMillan Date: Fri, 28 Feb 2014 16:35:03 -0600 Subject: Fix link to tox --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 0255c484..18a05050 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -67,7 +67,7 @@ To run the tests, clone the repository, and then: # Run the tests rest_framework/runtests/runtests.py -You can also use the excellent `[tox][tox]` testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run: +You can also use the excellent [tox][tox] testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run: tox -- cgit v1.2.3 From 971578ca345c3d3bae7fd93b87c41d43483b6f05 Mon Sep 17 00:00:00 2001 From: Andreas Pelme Date: Sun, 2 Mar 2014 12:40:30 +0100 Subject: Support for running the test suite with py.test * Get rid of runtests.py * Moved test code from rest_framework/tests and rest_framework/runtests to tests * Invoke py.test from setup.py * Invoke py.test from Travis * Invoke py.test from tox * Changed setUpClass to be just plain setUp in test_permissions.py * Updated contribution guideline to show how to invoke py.test --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 5a5d1a80..09cc00b3 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -65,7 +65,7 @@ To run the tests, clone the repository, and then: pip install -r optionals.txt # Run the tests - rest_framework/runtests/runtests.py + py.test You can also use the excellent `[tox][tox]` testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run: -- cgit v1.2.3 From 00c0dfc66fd2426a63e6eec498395740b2c3e63b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 19 Aug 2014 16:29:05 +0100 Subject: Documentation on runtests.py --- docs/topics/contributing.md | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index d33843e1..3400bc8f 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -62,10 +62,44 @@ To run the tests, clone the repository, and then: virtualenv env source env/bin/activate pip install -r requirements.txt - pip install -r optionals.txt + pip install -r requirements-test.txt # Run the tests - py.test + ./runtests.py + +### Test options + +Run using a more concise output style. + + ./runtests -q + +Run the tests using a more concise output style, no coverage, no flake8. + + ./runtests --fast + +Don't run the flake8 code linting. + + ./runtests --nolint + +Only run the flake8 code linting, don't run the tests. + + ./runtests --lintonly + +Run the tests for a given test case. + + ./runtests MyTestCase + +Run the tests for a given test method. + + ./runtests MyTestCase.test_this_method + +Shorter form to run the tests for a given test method. + + ./runtests test_this_method + +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. + +### Running against multiple environments You can also use the excellent [tox][tox] testing tool to run the tests against all supported versions of Python and Django. Install `tox` globally, and then simply run: -- cgit v1.2.3 From dfab9af294972720f59890967cd9ae1a6c0796b6 Mon Sep 17 00:00:00 2001 From: Craig de Stigter Date: Fri, 3 Oct 2014 08:41:18 +1300 Subject: Minor: fix spelling and grammar, mostly in 3.0 announcement --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 3400bc8f..50b8ded1 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -109,7 +109,7 @@ You can also use the excellent [tox][tox] testing tool to run the tests against 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. -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 seperate issue without interfering with an ongoing pull requests. +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. 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. -- cgit v1.2.3 From 11edd01c34debbe3b689da91efd63cddab7b28c4 Mon Sep 17 00:00:00 2001 From: José Padilla Date: Fri, 17 Oct 2014 08:58:31 -0400 Subject: Add docs regarding linking third party packages --- docs/topics/contributing.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 3400bc8f..4fafb1b1 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -210,7 +210,9 @@ We recommend the [`django-reusable-app`][django-reusable-app] template as a good ## Linking to your package -Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. +Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. You can add your package under **Third party packages** of the API Guide section that best applies, like [Authentication][authentication] or [Permissions][permissions]. You can also link your package under the [Third Party Resources][third-party-resources] section. + +We also suggest adding it to the [REST Framework][rest-framework-grid] grid on Django Packages. [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html [code-of-conduct]: https://www.djangoproject.com/conduct/ @@ -225,3 +227,7 @@ Once your package is decently documented and available on PyPI open a pull reque [docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ [django-reusable-app]: https://github.com/dabapps/django-reusable-app +[authentication]: ../api-guide/authentication.md +[permissions]: ../api-guide/permissions.md +[third-party-resources]: third-party-resources.md +[rest-framework-grid]: https://www.djangopackages.com/grids/g/django-rest-framework/ -- cgit v1.2.3 From 440d61ab364da971973ae8d784e77e21e5cdaa7f Mon Sep 17 00:00:00 2001 From: Jochen Van de Velde Date: Sat, 8 Nov 2014 11:02:48 +0100 Subject: Fix some typos and other errors --- docs/topics/contributing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 96d9a98c..6c289938 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -10,9 +10,9 @@ There are many ways you can contribute to Django REST framework. We'd like it t 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. -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. +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. -Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. +Other really great ways you can help move the community forward include helping to answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. 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. @@ -33,7 +33,7 @@ Some tips on good issue reporting: * When describing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. * Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. * 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. -* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintainence overhead of REST framework, so that the focus can be on continued stability, bugfixes, and great documentation. +* Feature requests will often be closed with a recommendation that they be implemented outside of the core REST framework library. Keeping new feature requests implemented as third party libraries allows us to keep down the maintenance overhead of REST framework, so that the focus can be on continued stability, bugfixes, and great documentation. * Closing an issue doesn't necessarily mean the end of a discussion. If you believe your issue has been closed incorrectly, explain why and we'll consider if it needs to be reopened. ## Triaging issues @@ -52,7 +52,7 @@ To start developing on Django REST framework, clone the repo: git clone git@github.com:tomchristie/django-rest-framework.git -Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recommend you setup your editor to automatically indicated non-conforming styles. +Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recommend you set up your editor to automatically indicate non-conforming styles. ## Testing @@ -117,7 +117,7 @@ GitHub's documentation for working on pull requests is [available here][pull-req Always run the tests before submitting pull requests, and ideally run `tox` in order to check that your modifications are compatible with both Python 2 and Python 3, and that they run properly on all supported versions of Django. -Once you've made a pull request take a look at the travis build status in the GitHub interface and make sure the tests are runnning as you'd expect. +Once you've made a pull request take a look at the Travis build status in the GitHub interface and make sure the tests are running as you'd expect. ![Travis status][travis-status] @@ -131,7 +131,7 @@ Sometimes, in order to ensure your code works on various different versions of D The documentation for REST framework is built from the [Markdown][markdown] source files in [the docs directory][docs]. -There are many great markdown editors that make working with the documentation really easy. The [Mou editor for Mac][mou] is one such editor that comes highly recommended. +There are many great Markdown editors that make working with the documentation really easy. The [Mou editor for Mac][mou] is one such editor that comes highly recommended. ## Building the documentation @@ -153,7 +153,7 @@ Some other tips: * Keep paragraphs reasonably short. * Use double spacing after the end of sentences. -* Don't use the abbreviations such as 'e.g.' but instead use long form, such as 'For example'. +* Don't use abbreviations such as 'e.g.' but instead use the long form, such as 'For example'. ## Markdown style @@ -186,7 +186,7 @@ If you are hyperlinking to another REST framework document, you should use a rel [authentication]: ../api-guide/authentication.md -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. +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. ##### 3. Notes -- cgit v1.2.3 From d08cfb0559033acaefbc23863c43ef858c2c0e1c Mon Sep 17 00:00:00 2001 From: José Padilla Date: Mon, 17 Nov 2014 08:17:40 -0400 Subject: Fix runtests examples Correctly rename runtests examples to work with current runtests.py file.--- docs/topics/contributing.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 6c289938..52f6e287 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -71,31 +71,31 @@ To run the tests, clone the repository, and then: Run using a more concise output style. - ./runtests -q + ./runtests.py -q Run the tests using a more concise output style, no coverage, no flake8. - ./runtests --fast + ./runtests.py --fast Don't run the flake8 code linting. - ./runtests --nolint + ./runtests.py --nolint Only run the flake8 code linting, don't run the tests. - ./runtests --lintonly + ./runtests.py --lintonly Run the tests for a given test case. - ./runtests MyTestCase + ./runtests.py MyTestCase Run the tests for a given test method. - ./runtests MyTestCase.test_this_method + ./runtests.py MyTestCase.test_this_method Shorter form to run the tests for a given test method. - ./runtests test_this_method + ./runtests.py test_this_method 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. -- cgit v1.2.3 From 84d9c4b46eacda54b31a3779c623554758f4dccc Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Wed, 22 Oct 2014 21:36:11 +0100 Subject: Change site_dir to html to match mkdocs.py --- docs/topics/contributing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 52f6e287..5809af65 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -135,15 +135,15 @@ There are many great Markdown editors that make working with the documentation r ## Building the documentation -To build the documentation, simply run the `mkdocs.py` script. +To build the documentation, simply install MkDocs with `pip install mkdocs` and then run the following command. - ./mkdocs.py + mkdocs build This will build the html output into the `html` directory. -You can build the documentation and open a preview in a browser window by using the `-p` flag. +You can build the documentation and open a preview in a browser window by using the `serve` command. - ./mkdocs.py -p + mkdocs serve ## Language style -- cgit v1.2.3 From 2ddef2d3263b2187fd502e42eaaecc3a4f0ad2b2 Mon Sep 17 00:00:00 2001 From: Dougal Matthews Date: Thu, 23 Oct 2014 14:10:23 +0100 Subject: Drop simply from the mkdocs install lines It is still simple tho', honest ;) --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 5809af65..c7991a0f 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -135,7 +135,7 @@ There are many great Markdown editors that make working with the documentation r ## Building the documentation -To build the documentation, simply install MkDocs with `pip install mkdocs` and then run the following command. +To build the documentation, install MkDocs with `pip install mkdocs` and then run the following command. mkdocs build -- cgit v1.2.3 From c7701cd75a746a863ddf8c517a4ec9c6272d66ca Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 25 Nov 2014 16:08:48 +0000 Subject: Tweak --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index c7991a0f..7654136c 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -139,7 +139,7 @@ To build the documentation, install MkDocs with `pip install mkdocs` and then ru mkdocs build -This will build the html output into the `html` directory. +This will build the documentation into the `site` directory. You can build the documentation and open a preview in a browser window by using the `serve` command. -- cgit v1.2.3 From 9b88c096e0627f1f054a50097d653543909662ab Mon Sep 17 00:00:00 2001 From: José Padilla Date: Wed, 26 Nov 2014 18:12:12 -0400 Subject: Remove Third party packages section Information about Third party packages is already covered under the Third Party Resources topic--- docs/topics/contributing.md | 20 -------------------- 1 file changed, 20 deletions(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 7654136c..30a9678f 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -198,21 +198,6 @@ If you want to draw attention to a note or warning, use a pair of enclosing line --- -# Third party packages - -New features to REST framework are generally recommended to be implemented as third party libraries that are developed outside of the core framework. Ideally third party libraries should be properly documented and packaged, and made available on PyPI. - -## Getting started - -If you have some functionality that you would like to implement as a third party package it's worth contacting the [discussion group][google-group] as others may be willing to get involved. We strongly encourage third party package development and will always try to prioritize time spent helping their development, documentation and packaging. - -We recommend the [`django-reusable-app`][django-reusable-app] template as a good resource for getting up and running with implementing a third party Django package. - -## Linking to your package - -Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. You can add your package under **Third party packages** of the API Guide section that best applies, like [Authentication][authentication] or [Permissions][permissions]. You can also link your package under the [Third Party Resources][third-party-resources] section. - -We also suggest adding it to the [REST Framework][rest-framework-grid] grid on Django Packages. [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html [code-of-conduct]: https://www.djangoproject.com/conduct/ @@ -226,8 +211,3 @@ We also suggest adding it to the [REST Framework][rest-framework-grid] grid on D [markdown]: http://daringfireball.net/projects/markdown/basics [docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ -[django-reusable-app]: https://github.com/dabapps/django-reusable-app -[authentication]: ../api-guide/authentication.md -[permissions]: ../api-guide/permissions.md -[third-party-resources]: third-party-resources.md -[rest-framework-grid]: https://www.djangopackages.com/grids/g/django-rest-framework/ -- cgit v1.2.3 From 05a86e3d6539f4f33d440daf04fa8b0e9b1e371a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 28 Nov 2014 12:51:44 +0000 Subject: Docs. Minor tweaks. --- docs/topics/contributing.md | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 30a9678f..99f4fc3c 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -152,7 +152,6 @@ Documentation should be in American English. The tone of the documentation is v Some other tips: * Keep paragraphs reasonably short. -* Use double spacing after the end of sentences. * Don't use abbreviations such as 'e.g.' but instead use the long form, such as 'For example'. ## Markdown style -- cgit v1.2.3 From bc0c25df3020772124e1767895c7e7cb60d974c1 Mon Sep 17 00:00:00 2001 From: José Padilla Date: Mon, 1 Dec 2014 17:31:11 -0400 Subject: Consolidate Django and test requirements --- docs/topics/contributing.md | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/topics/contributing.md') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 99f4fc3c..c9626ebf 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -62,7 +62,6 @@ To run the tests, clone the repository, and then: virtualenv env source env/bin/activate pip install -r requirements.txt - pip install -r requirements-test.txt # Run the tests ./runtests.py -- cgit v1.2.3