[Django] #27355: Emphasizes the role of TrigramExtension and UnaccentExtension in the documentation
Django
documentation
-------------------------------------+-------------------------------------
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Severity: Normal | Keywords: postgres unaccent
| trigram
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
`TrigramExtension` and `UnaccentExtension` have been introduced in
`django.contrib.postgres` in Django 1.10 to help developpers to activate
the pg_trim and unaccent extension of postgres when they are using the
corresponding ORM lookup.
Even though I feel pretty comfortable with the Django doc usually, this
time, I did not find `UnaccentExtension` in few minutes. In local, I did
the extension activation by myself (since I did not read the relevant part
of the doc) but get stuck when trying to execute my unit tests. I think
these migration operations are not stressed enough in the doc. I believe
it is [referenced only
here](https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/lookups/),
each time in a sentence which barely says when to use it.
I think there should be an introduction at the top of the page linked
above saying something like: "The lookups above need the activation of
extensions in Postgres. To enable them, you are advised to create a Django
migration which will apply the relevant operation", where the "relevant
operation" is referring to either TrigramExtension or UnaccentExtension,
but I don't know how to transcribe it :/
--
Ticket URL: <https://code.djangoproject.com/ticket/27355>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
documentation
-------------------------------------+-------------------------------------
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage:
trigram | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
Comment:
It's not entirely clear to me why you want the instructions repeated
twice, once at the top of the page and once within the docs for each
extension -- or did I misunderstand the suggestion? Another consideration
is that future lookups might not require activation of an extension.
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:1>
Django
documentation
-------------------------------------+-------------------------------------
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage:
trigram | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Maxime Lorant):
Replying to [comment:1 Tim Graham]:
> It's not entirely clear to me why you want the instructions repeated
twice, once at the top of the page and once within the docs for each
extension -- or did I misunderstand the suggestion? Another consideration
is that future lookups might not require activation of an extension.
I don't think it should be write twice, but I guess it would not hurt if
the usefulness of these two classes was more explicit so it can be easier
to find it.
(It is marked as cleanup, we can live with the current wording, but I
think it could be better :) )
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:2>
Django
documentation
-------------------------------------+-------------------------------------
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage:
trigram | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham):
Maybe moving the `HStoreExtension` example from
https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField
to https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/
and explaining that the same usage principles apply for all extensions
would be help?
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:3>
Django
documentation
-------------------------------------+-------------------------------------
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage:
trigram | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Maxime Lorant):
That would be great, yes, and it does involve a lot of changes.
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:5>
Django
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Levi Velázquez):
What Maxime suggested sounds good, I think we can add an section on
https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/
named "Create extension using migrations" and add the example from
https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField.
About Tom reply, why it does involve a lot of changes ?
I'm interesting to take this cleanup, It would be my first contribution to
Django.
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:6>
Django
Reporter: Maxime Lorant | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Maxime Lorant):
Replying to [comment:6 Levi Velázquez]:
> About Tom reply, why it does involve a lot of changes ?
>
> I'm interesting to take this cleanup, It would be my first contribution
to Django.
I forgot a "not", you should read: "it does **NOT** involve [...] " :-)
It's merely copy-pasting in another page with some adjustments.
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:7>
Django
Reporter: Maxime Lorant | Owner: ntuckovic
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: nobody => ntuckovic
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:8>
Django
Reporter: Maxime Lorant | Owner: ntuckovic
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/7491 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:9>
Django
Reporter: Maxime Lorant | Owner: ntuckovic
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 0 => 1
Comment:
Looks fine, apart from some spelling/formatting corrections. These have
been noted as comments on the PR.
For clarity, I've set the "patch needs improvement" checkbox as there are
two sets of suggested fixes on the PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:10>
Django
Reporter: Maxime Lorant | Owner: ntuckovic
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
-------------------------------------+-------------------------------------
* cc: reinout@… (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:11>
Django
Reporter: Maxime Lorant | Owner: ntuckovic
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"4de8aaf7ffc91b91cbb70e9db406abe9b160575a" 4de8aaf]:
{{{
#!CommitTicketReference repository=""
revision="4de8aaf7ffc91b91cbb70e9db406abe9b160575a"
Fixed #27355 -- Added “Creating extension using migrations” docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:12>
Django
Reporter: Maxime Lorant | Owner: ntuckovic
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.10
Keywords: postgres unaccent | Triage Stage: Accepted
trigram |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"1b6649c6d177286852cc9c13fdf0fa65f17cb1f8" 1b6649c6]:
{{{
#!CommitTicketReference repository=""
revision="1b6649c6d177286852cc9c13fdf0fa65f17cb1f8"
[1.10.x] Fixed #27355 -- Added “Creating extension using migrations” docs.
Backport of 4de8aaf7ffc91b91cbb70e9db406abe9b160575a from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27355#comment:13>