From 9c9d5bd859d4da0c7191525d77e57debd5c8d23c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 18 Dec 2014 13:35:42 +0000 Subject: [PATCH 1/3] Added project management docs. --- docs/index.md | 2 + docs/topics/project-management.md | 134 ++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 137 insertions(+) create mode 100644 docs/topics/project-management.md diff --git a/docs/index.md b/docs/index.md index 52e42fc9a..ba915459c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -199,6 +199,7 @@ General guides to using REST framework. * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] * [Third Party Resources][third-party-resources] * [Contributing to REST framework][contributing] +* [Project management][project-management] * [2.0 Announcement][rest-framework-2-announcement] * [2.2 Announcement][2.2-announcement] * [2.3 Announcement][2.3-announcement] @@ -317,6 +318,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [browsableapi]: topics/browsable-api.md [rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md [contributing]: topics/contributing.md +[project-management]: topics/project-management.md [third-party-resources]: topics/third-party-resources.md [rest-framework-2-announcement]: topics/rest-framework-2-announcement.md [2.2-announcement]: topics/2.2-announcement.md diff --git a/docs/topics/project-management.md b/docs/topics/project-management.md new file mode 100644 index 000000000..f581cabd3 --- /dev/null +++ b/docs/topics/project-management.md @@ -0,0 +1,134 @@ +# Project management + +> "No one can whistle a symphony; it takes a whole orchestra to play it" +> +> — Halford E. Luccock + +This document outlines our project management processes for REST framework. + +The aim is to ensure that the project has a high +["bus factor"][bus-factor], and can continue to remain well supported for the foreseeable future. Suggestions for improvements to our process are welcome. + +--- + +## Maintenance team + +We have a quarterly maintenance cycle where new members may join the maintenance team. We currently cap the size of the team at 5 members, and may encourage folks to step out of the team for a cycle to allow new members to participate. + +#### Current team + +The [maintenance team for Q1 2015](https://github.com/tomchristie/django-rest-framework/issues/2190): + +* [@tomchristie](https://github.com/tomchristie/) +* [@xordoquy](https://github.com/xordoquy/) (Release manager.) +* [@carltongibson](https://github.com/carltongibson/) +* [@kevin-brown](https://github.com/kevin-brown/) +* [@jpadilla](https://github.com/jpadilla/) + +#### Maintenance cycles + +Each maintenance cycle is initiated by an issue being opened with the `Process` label. + +* To be considered for a maintainer role simply comment against the issue. +* Existing members must explicitly opt-in to the next cycle by check-marking their name. +* The final decision on the incoming team will be made by `@tomchristie`. + +Members of the maintenance team will be added as collaborators to the repository. + +The following template should be used for the description of the issue, and serves as the formal process for selecting the team. + + This issue is for determining the maintenance team for the *** period. + + Please see the [Project management](http://www.django-rest-framework.org/topics/project-management/) section of our documentation for more details. + + --- + + #### Renewing existing members. + + The following people are the current maintenance team. Please checkmark your name if you wish to continue to have write permission on the repository for the *** period. + + - [ ] @*** + - [ ] @*** + - [ ] @*** + - [ ] @*** + - [ ] @*** + + --- + + #### New members. + + If you wish to be considered for this or a future date, please comment against this or subsequent issues. + +#### Responsibilities of team members + +Team members have the following responsibilities. + +* Add triage labels and milestones to tickets. +* Close invalid or resolved tickets. +* Merge finalized pull requests. +* Build and deploy the documentation, using `mkdocs gh-deploy`. + +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]. + +It should be noted that participating actively in the REST framework project clearly **does not require being part of the maintenance team**. Almost every import part of issue triage and project improvement can be actively worked on regardless of your collaborator status on the repository. + +--- + +## Release process + +The release manager is selected on every quarterly maintenance cycle. + +* The manager should be selected by `@tomchristie`. +* The manager will then have the maintainer role added to PyPI package. +* The previous manager will then have the maintainer role removed from the PyPI package. + +Our PyPI releases will be handled by either the current release manager, or by `@tomchristie`. Every release should have an open issue tagged with the `Release` label and marked against the appropriate milestone. + +The following template should be used for the description of the issue, and serves as a release checklist. + + Release manager is @***. + Pull request is #***. + + Checklist: + + - [ ] Create pull request for [release notes](https://github.com/tomchristie/django-rest-framework/blob/master/docs/topics/release-notes.md) based on the [*.*.* milestone](https://github.com/tomchristie/django-rest-framework/milestones/***). + - [ ] Ensure the pull request increments the version to `*.*.*` in [`restframework/__init__.py`](https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/__init__.py). + - [ ] Confirm with @tomchristie that release is finalized and ready to go. + - [ ] Ensure that release date is included in pull request. + - [ ] Merge the release pull request. + - [ ] Push the package to PyPI with `./setup.py publish`. + - [ ] Tag the release, with `git tag -a *.*.* -m 'version *.*.*'; git push --tags`. + - [ ] Deploy the documentation with `mkdocs gh-deploy`. + - [ ] Make a release announcement on the [discussion group](https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework). + - [ ] Make a release announcement on twitter. + - [ ] Close the milestone on GitHub. + +When pushing the release to PyPI ensure that your environment has been installed from our development `requirement.txt`, so that documentation and PyPI installs are consistently being built against a pinned set of packages. + +--- + +## Project ownership + +The PyPI package is owned by `@tomchristie`. As a backup `@j4mie` also has ownership of the package. + +If `@tomchristie` ceases to participate in the project then `@j4mie` has responsibility for handing over ownership duties. + +#### Outstanding management & ownership issues + +The following issues still need to be addressed: + +* [Consider moving the repo into a proper GitHub organization][github-org]. +* Ensure `@jamie` has back-up access to the `django-rest-framework.org` domain setup and admin. +* Document ownership of the [live example][sandbox] API. +* Document ownership of the [mailing list][mailing-list] and IRC channel. + +[bus-factor]: http://en.wikipedia.org/wiki/Bus_factor +[un-triaged]: https://github.com/tomchristie/django-rest-framework/issues?q=is%3Aopen+no%3Alabel +[github-org]: https://github.com/tomchristie/django-rest-framework/issues/2162 +[sandbox]: http://restframework.herokuapp.com/ +[mailing-list]: https://groups.google.com/forum/#!forum/django-rest-framework diff --git a/mkdocs.yml b/mkdocs.yml index 9513f04f7..d16a2a595 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,6 +46,7 @@ pages: - ['topics/rest-hypermedia-hateoas.md', 'Topics', 'REST, Hypermedia & HATEOAS'] - ['topics/third-party-resources.md', 'Topics', 'Third Party Resources'] - ['topics/contributing.md', 'Topics', 'Contributing to REST framework'] + - ['topics/project-management.md', 'Topics', 'Project management'] - ['topics/rest-framework-2-announcement.md', 'Topics', '2.0 Announcement'] - ['topics/2.2-announcement.md', 'Topics', '2.2 Announcement'] - ['topics/2.3-announcement.md', 'Topics', '2.3 Announcement'] From d60ecfc4982ff5ccfacd285404fc54e3e0fd6567 Mon Sep 17 00:00:00 2001 From: Tymur Maryokhin Date: Thu, 18 Dec 2014 16:03:15 +0100 Subject: [PATCH 2/3] Assert fields in `exclude` are model fields --- rest_framework/serializers.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rest_framework/serializers.py b/rest_framework/serializers.py index 8de22f4b9..ed709d848 100644 --- a/rest_framework/serializers.py +++ b/rest_framework/serializers.py @@ -880,6 +880,10 @@ class ModelSerializer(Serializer): exclude = getattr(self.Meta, 'exclude', None) if exclude is not None: for field_name in exclude: + assert field_name in fields, ( + 'The field in the `exclude` option must be a model field. Got %s.' % + field_name + ) fields.remove(field_name) # Determine the set of model fields, and the fields that they map to. From 7105c1308e08a756fcb4131168e3187b0bc1ddee Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 18 Dec 2014 15:42:27 +0000 Subject: [PATCH 3/3] Add OPTIONS/metadata to docs index --- docs/api-guide/metadata.md | 2 +- docs/index.md | 2 ++ mkdocs.yml | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/api-guide/metadata.md b/docs/api-guide/metadata.md index c3e511487..247ae988f 100644 --- a/docs/api-guide/metadata.md +++ b/docs/api-guide/metadata.md @@ -1,4 +1,4 @@ - +source: metadata.py --- diff --git a/docs/index.md b/docs/index.md index ba915459c..8a96fc9fb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -181,6 +181,7 @@ The API guide is your complete reference manual to all the functionality provide * [Filtering][filtering] * [Pagination][pagination] * [Content negotiation][contentnegotiation] +* [Metadata][metadata] * [Format suffixes][formatsuffixes] * [Returning URLs][reverse] * [Exceptions][exceptions] @@ -305,6 +306,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [filtering]: api-guide/filtering.md [pagination]: api-guide/pagination.md [contentnegotiation]: api-guide/content-negotiation.md +[metadata]: api-guide/metadata.md [formatsuffixes]: api-guide/format-suffixes.md [reverse]: api-guide/reverse.md [exceptions]: api-guide/exceptions.md diff --git a/mkdocs.yml b/mkdocs.yml index d16a2a595..85f4d2443 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,7 @@ pages: - ['api-guide/filtering.md', 'API Guide', 'Filtering'] - ['api-guide/pagination.md', 'API Guide', 'Pagination'] - ['api-guide/content-negotiation.md', 'API Guide', 'Content negotiation'] + - ['api-guide/metadata.md', 'API Guide', 'Metadata'] - ['api-guide/format-suffixes.md', 'API Guide', 'Format suffixes'] - ['api-guide/reverse.md', 'API Guide', 'Returning URLs'] - ['api-guide/exceptions.md', 'API Guide', 'Exceptions']