diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..0ba2c5d9d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,7 @@ +blank_issues_enabled: false +contact_links: +- name: Discussions + url: https://github.com/encode/django-rest-framework/discussions + about: > + The "Discussions" forum is where you want to start. 💖 + Please note that at this point in its lifespan, we consider Django REST framework to be feature-complete. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 644a719c8..af7d55f13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,4 +2,6 @@ At this point in its lifespan we consider Django REST framework to be essentially feature-complete. We may accept pull requests that track the continued development of Django versions, but would prefer not to accept new features or code formatting changes. +Apart from minor documentation changes, the [GitHub discussions page](https://github.com/encode/django-rest-framework/discussions) should generally be your starting point. Please only open a pull request if you've been recommended to do so **after discussion**. + The [Contributing guide in the documentation](https://www.django-rest-framework.org/community/contributing/) gives some more information on our process and code of conduct. diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index e6d7774a6..0ea8b4158 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -110,7 +110,7 @@ You'll need to remember to also set your custom throttle class in the `'DEFAULT_ The built-in throttle implementations are open to [race conditions][race], so under high concurrency they may allow a few extra requests through. -If your project relies on guaranteeing the number of requests during concurrent requests, you will need to implement your own throttle class. +If your project relies on guaranteeing the number of requests during concurrent requests, you will need to implement your own throttle class. See [issue #5181][gh5181] for more details. --- @@ -220,4 +220,5 @@ The following is an example of a rate throttle, that will randomly throttle 1 in [identifying-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster [cache-setting]: https://docs.djangoproject.com/en/stable/ref/settings/#caches [cache-docs]: https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache +[gh5181]: https://github.com/encode/django-rest-framework/issues/5181 [race]: https://en.wikipedia.org/wiki/Race_condition#Data_race diff --git a/docs/api-guide/validators.md b/docs/api-guide/validators.md index 57bcb8628..e3407e8a3 100644 --- a/docs/api-guide/validators.md +++ b/docs/api-guide/validators.md @@ -13,7 +13,7 @@ Most of the time you're dealing with validation in REST framework you'll simply However, sometimes you'll want to place your validation logic into reusable components, so that it can easily be reused throughout your codebase. This can be achieved by using validator functions and validator classes. -## Validation in REST framework +## Validation in REST framework Validation in Django REST framework serializers is handled a little differently to how validation works in Django's `ModelForm` class. @@ -75,7 +75,7 @@ This validator should be applied to *serializer fields*, like so: validators=[UniqueValidator(queryset=BlogPost.objects.all())] ) -## UniqueTogetherValidator +## UniqueTogetherValidator This validator can be used to enforce `unique_together` constraints on model instances. It has two required arguments, and a single optional `messages` argument: @@ -92,7 +92,7 @@ The validator should be applied to *serializer classes*, like so: # ... class Meta: # ToDo items belong to a parent list, and have an ordering defined - # by the 'position' field. No two items in a given list may share + # by the 'position' field. No two items in a given list may share # the same position. validators = [ UniqueTogetherValidator( @@ -166,7 +166,7 @@ If you want the date field to be entirely hidden from the user, then use `Hidden --- -**Note:** `HiddenField()` does not appear in `partial=True` serializer (when making `PATCH` request). +**Note:** `HiddenField()` does not appear in `partial=True` serializer (when making `PATCH` request). --- diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 5a9188943..b47059f29 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -4,6 +4,8 @@ > > — [Tim Berners-Lee][cite] +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. + !!! note 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. @@ -28,9 +30,22 @@ The [Django code of conduct][code-of-conduct] gives a fuller set of guidelines f # Issues +Our contribution process is that the [GitHub discussions page](https://github.com/encode/django-rest-framework/discussions) should generally be your starting point. Some tips on good potential issue reporting: + * 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. +* Search the GitHub project page for related items, and make sure you're running the latest version of REST framework before reporting an issue. * 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. +## 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 + +* 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, could the feature request instead be implemented as a third party package? +* 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. + # Development To start developing on Django REST framework, first create a Fork from the diff --git a/docs/community/project-management.md b/docs/community/project-management.md index daf2cda8d..4f203e13b 100644 --- a/docs/community/project-management.md +++ b/docs/community/project-management.md @@ -34,6 +34,7 @@ Further notes for maintainers: * Code changes should come in the form of a pull request - do not push directly to master. * Maintainers should typically not merge their own pull requests. * Each issue/pull request should have exactly one label once triaged. +* Search for un-triaged issues with [is:open no:label][un-triaged]. --- @@ -156,6 +157,7 @@ The following issues still need to be addressed: * Document ownership and management of the security mailing list. [bus-factor]: https://en.wikipedia.org/wiki/Bus_factor +[un-triaged]: https://github.com/encode/django-rest-framework/issues?q=is%3Aopen+no%3Alabel [transifex-project]: https://www.transifex.com/projects/p/django-rest-framework/ [transifex-client]: https://pypi.org/project/transifex-client/ [translation-memory]: http://docs.transifex.com/guides/tm#let-tm-automatically-populate-translations