New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Full "Getting started" instructions #250

Closed
pquentin opened this Issue Aug 23, 2013 · 12 comments

Comments

Projects
None yet
2 participants
@pquentin
Contributor

pquentin commented Aug 23, 2013

django-reversion is an awesome project, thanks! The documentation lacks a full tutorial that explains how to get started. A good example of such a tutorial is the South one: http://south.readthedocs.org/en/latest/tutorial/part1.html.

Home.md is already there and is nearly complete: I tried to complete it to make simpler for new-comers to understand what should be done to use the project. (It was difficult for me to understand how things worked when I first used django-reversion this week.)

Since django-reversion uses a github wiki for documentation, it's not possible to submit a pull request to the docs. I instead cloned the wiki, modified it, and formatted a patch available on gist.github.com: https://gist.github.com/anonymous/6319615. You can git apply it if it looks good. I'd be happy to improve it further too!

Thanks.

@etianen

This comment has been minimized.

Show comment
Hide comment
@etianen

etianen Aug 26, 2013

Owner

Thanks for looking at this!

The major change you seem to have made is adding a section about using the RevisionMiddleware. This has previously been kept on the Low Level API page, since it's not needed for the admin integration to work. It's also going to be a little outdated with the release of Django 1.6, when the TransactionMiddleware is deprecated in favour of the new atomic decorators and context managers.

I'm thinking that django-reversion is long overdue integration with ReadTheDocs, since this will allow precisely the sort of pull request behaviour that you're talking about.

I'm not sure whether, in this case, adding such prominence to the RevisionMiddleware is justified, since the vast majority of django-reversion users seem to be using the admin integration exclusively.

On 23 Aug 2013, at 15:02, pquentin notifications@github.com wrote:

django-reversion is an awesome project, thanks! The documentation lacks a full tutorial that explains how to get started. A good example of such a tutorial is the South one: http://south.readthedocs.org/en/latest/tutorial/part1.html.

Home.md is already there and is nearly complete: I tried to complete it to make simpler for new-comers to understand what should be done to use the project. (It was difficult for me to understand how things worked when I first used django-reversion this week.)

Since django-reversion uses a github wiki for documentation, it's not possible to submit a pull request to the docs. I instead cloned the wiki, modified it, and formatted a patch available on gist.github.com: https://gist.github.com/anonymous/6319615. You can git apply it if it looks good. I'd be happy to improve it further too!

Thanks.


Reply to this email directly or view it on GitHub.

Owner

etianen commented Aug 26, 2013

Thanks for looking at this!

The major change you seem to have made is adding a section about using the RevisionMiddleware. This has previously been kept on the Low Level API page, since it's not needed for the admin integration to work. It's also going to be a little outdated with the release of Django 1.6, when the TransactionMiddleware is deprecated in favour of the new atomic decorators and context managers.

I'm thinking that django-reversion is long overdue integration with ReadTheDocs, since this will allow precisely the sort of pull request behaviour that you're talking about.

I'm not sure whether, in this case, adding such prominence to the RevisionMiddleware is justified, since the vast majority of django-reversion users seem to be using the admin integration exclusively.

On 23 Aug 2013, at 15:02, pquentin notifications@github.com wrote:

django-reversion is an awesome project, thanks! The documentation lacks a full tutorial that explains how to get started. A good example of such a tutorial is the South one: http://south.readthedocs.org/en/latest/tutorial/part1.html.

Home.md is already there and is nearly complete: I tried to complete it to make simpler for new-comers to understand what should be done to use the project. (It was difficult for me to understand how things worked when I first used django-reversion this week.)

Since django-reversion uses a github wiki for documentation, it's not possible to submit a pull request to the docs. I instead cloned the wiki, modified it, and formatted a patch available on gist.github.com: https://gist.github.com/anonymous/6319615. You can git apply it if it looks good. I'd be happy to improve it further too!

Thanks.


Reply to this email directly or view it on GitHub.

@pquentin

This comment has been minimized.

Show comment
Hide comment
@pquentin

pquentin Aug 26, 2013

Contributor

The other great feature of RTD is the ability to see the docs for the version you're using: the docs for Django 1.5/1.6/1.7 would be different since it looks like every django-reversion is tied to a specific Django version.

I'm a bit confused here: if most django-reversion users use admin integration exclusively, how do they save new revisions? Don't they use the low level API?

Contributor

pquentin commented Aug 26, 2013

The other great feature of RTD is the ability to see the docs for the version you're using: the docs for Django 1.5/1.6/1.7 would be different since it looks like every django-reversion is tied to a specific Django version.

I'm a bit confused here: if most django-reversion users use admin integration exclusively, how do they save new revisions? Don't they use the low level API?

@etianen

This comment has been minimized.

Show comment
Hide comment
@etianen

etianen Aug 26, 2013

Owner

When you save a model in the django admin site, and your model is registered with a subclass VersionAdmin, a new version is saved. That, coupled with the admin UI for recovery and rollback, amounts to complete admin-level version control, which is what most people seem to be using.

On 26 Aug 2013, at 10:54, pquentin notifications@github.com wrote:

The other great feature of RTD is the ability to see the docs for the version you're using: the docs for Django 1.5/1.6/1.7 would be different since it looks like every django-reversion is tied to a specific Django version.

I'm a bit confused here: if most django-reversion users use admin integration exclusively, how do they save new revisions? Don't they use the low level API?


Reply to this email directly or view it on GitHub.

Owner

etianen commented Aug 26, 2013

When you save a model in the django admin site, and your model is registered with a subclass VersionAdmin, a new version is saved. That, coupled with the admin UI for recovery and rollback, amounts to complete admin-level version control, which is what most people seem to be using.

On 26 Aug 2013, at 10:54, pquentin notifications@github.com wrote:

The other great feature of RTD is the ability to see the docs for the version you're using: the docs for Django 1.5/1.6/1.7 would be different since it looks like every django-reversion is tied to a specific Django version.

I'm a bit confused here: if most django-reversion users use admin integration exclusively, how do they save new revisions? Don't they use the low level API?


Reply to this email directly or view it on GitHub.

@pquentin

This comment has been minimized.

Show comment
Hide comment
@pquentin

pquentin Aug 26, 2013

Contributor

OK, I get it. Most people don't update models themselves but exclusively use the admin to make changes. Thanks for the explanations! If I understand correctly, the main uses cases are:

  • only use the Django admin (most users)
  • save every modification on every request (.... me)
  • manually specify which transaction should use revisions

Is this correct? If I updated the docs to make it extremely for those categories to know what to do and what every option does, would it be useful? For example, "django-reversion can be used to add a powerful rollback and recovery facility to your admin site." doesn't say explicitely that "When you save a model in the django admin site, and your model is registered with a subclass VersionAdmin, a new version is saved."

I would be glad to help with the RTD integration, too.

Contributor

pquentin commented Aug 26, 2013

OK, I get it. Most people don't update models themselves but exclusively use the admin to make changes. Thanks for the explanations! If I understand correctly, the main uses cases are:

  • only use the Django admin (most users)
  • save every modification on every request (.... me)
  • manually specify which transaction should use revisions

Is this correct? If I updated the docs to make it extremely for those categories to know what to do and what every option does, would it be useful? For example, "django-reversion can be used to add a powerful rollback and recovery facility to your admin site." doesn't say explicitely that "When you save a model in the django admin site, and your model is registered with a subclass VersionAdmin, a new version is saved."

I would be glad to help with the RTD integration, too.

@etianen

This comment has been minimized.

Show comment
Hide comment
@etianen

etianen Aug 28, 2013

Owner

Help with the RTD integration would be amazing! I've got almost no time at the moment, so documentation help is greatly appreciated.

My suggested path would be:

  1. Integrate existing documention, with current wording, as .rst files for RTD. For this purpose, I'm happy to make you a committer.
  2. Get the RTD site up and running. At this point, we have baseline documentation! Woo!
  3. Apply your proposed changes, with three use-cases, to the getting started documentation. Tweak, then publish!

Does this sound reasonable? Would you like commit access for this purpose?

Thanks for your suggestions and help so far! :D

On 26 Aug 2013, at 13:09, pquentin notifications@github.com wrote:

OK, I get it. Most people don't update models themselves but exclusively use the admin to make changes. Thanks for the explanations! If I understand correctly, the main uses cases are:

only use the Django admin (most users)
save every modification on every request (.... me)
manually specify which transaction should use revisions
Is this correct? If I updated the docs to make it extremely for those categories to know what to do and what every option does, would it be useful? For example, "django-reversion can be used to add a powerful rollback and recovery facility to your admin site." doesn't say explicitely that "When you save a model in the django admin site, and your model is registered with a subclass VersionAdmin, a new version is saved."

I would be glad to help with the RTD integration, too.


Reply to this email directly or view it on GitHub.

Owner

etianen commented Aug 28, 2013

Help with the RTD integration would be amazing! I've got almost no time at the moment, so documentation help is greatly appreciated.

My suggested path would be:

  1. Integrate existing documention, with current wording, as .rst files for RTD. For this purpose, I'm happy to make you a committer.
  2. Get the RTD site up and running. At this point, we have baseline documentation! Woo!
  3. Apply your proposed changes, with three use-cases, to the getting started documentation. Tweak, then publish!

Does this sound reasonable? Would you like commit access for this purpose?

Thanks for your suggestions and help so far! :D

On 26 Aug 2013, at 13:09, pquentin notifications@github.com wrote:

OK, I get it. Most people don't update models themselves but exclusively use the admin to make changes. Thanks for the explanations! If I understand correctly, the main uses cases are:

only use the Django admin (most users)
save every modification on every request (.... me)
manually specify which transaction should use revisions
Is this correct? If I updated the docs to make it extremely for those categories to know what to do and what every option does, would it be useful? For example, "django-reversion can be used to add a powerful rollback and recovery facility to your admin site." doesn't say explicitely that "When you save a model in the django admin site, and your model is registered with a subclass VersionAdmin, a new version is saved."

I would be glad to help with the RTD integration, too.


Reply to this email directly or view it on GitHub.

@pquentin

This comment has been minimized.

Show comment
Hide comment
@pquentin

pquentin Aug 28, 2013

Contributor

Sure, this seems reasonable! Temporary commit access will help with setting up RTD.

After creating the django-reversion project on RTD and setting you as the RTD owner, I'll probably stick with pull requests so that you can approve any changes. If anything, my native language isn't English. :)

Contributor

pquentin commented Aug 28, 2013

Sure, this seems reasonable! Temporary commit access will help with setting up RTD.

After creating the django-reversion project on RTD and setting you as the RTD owner, I'll probably stick with pull requests so that you can approve any changes. If anything, my native language isn't English. :)

@etianen

This comment has been minimized.

Show comment
Hide comment
@etianen

etianen Aug 28, 2013

Owner

Congratulations! You are now a committer!

With great power comes great responsibility, of course, but you seem like a responsible type. :P

On 28 Aug 2013, at 15:24, pquentin notifications@github.com wrote:

Sure, this seems reasonable! Temporary commit access will help with setting up RTD.

After creating the django-reversion project on RTD and setting you as the RTD owner, I'll probably stick with pull requests so that you can approve any changes. If anything, my native language isn't English. :)


Reply to this email directly or view it on GitHub.

Owner

etianen commented Aug 28, 2013

Congratulations! You are now a committer!

With great power comes great responsibility, of course, but you seem like a responsible type. :P

On 28 Aug 2013, at 15:24, pquentin notifications@github.com wrote:

Sure, this seems reasonable! Temporary commit access will help with setting up RTD.

After creating the django-reversion project on RTD and setting you as the RTD owner, I'll probably stick with pull requests so that you can approve any changes. If anything, my native language isn't English. :)


Reply to this email directly or view it on GitHub.

@pquentin

This comment has been minimized.

Show comment
Hide comment
@pquentin

pquentin Aug 29, 2013

Contributor

Thanks! I've pushed my changes: 98e7cf4. Most of the work was changing ` to ``, changing ```python to ::, and headers formatting. Please remove my push access, I don't need it anymore.

Here is the URL for the docs: https://django-reversion.readthedocs.org/en/latest/

You can create a RTD account, which will allow me to set you as the RTL maintainer. Once that's done, you'll be able to remove me from the maintainers list.

If you are happy with the conversion, feel free to close the issue!

Contributor

pquentin commented Aug 29, 2013

Thanks! I've pushed my changes: 98e7cf4. Most of the work was changing ` to ``, changing ```python to ::, and headers formatting. Please remove my push access, I don't need it anymore.

Here is the URL for the docs: https://django-reversion.readthedocs.org/en/latest/

You can create a RTD account, which will allow me to set you as the RTL maintainer. Once that's done, you'll be able to remove me from the maintainers list.

If you are happy with the conversion, feel free to close the issue!

@etianen

This comment has been minimized.

Show comment
Hide comment
@etianen

etianen Aug 29, 2013

Owner

Many thanks... I appreciate it!

I've created a RTD account with username etianen .

I'll have a proper review of this when my current project is launched, which will be about a week. I'm really pepped about the new documentation, but I really don't have enough waking hours to give it a proper look-through at the moment. It's at the top of my "things to do when the damn site is launched" list. :P

Best,

Dave.

On 29 Aug 2013, at 10:59, pquentin notifications@github.com wrote:

Thanks! I've pushed my changes: 98e7cf4. Most of the work was changing `to``, changing```python to ::, and headers formatting. Please remove my push access, I don't need it anymore.

Here is the URL for the docs: https://django-reversion.readthedocs.org/en/latest/

You can create a RTD account, which will allow me to set you as the RTL maintainer. Once that's done, you'll be able to remove me from the maintainers list.

If you are happy with the conversion, feel free to close the issue!


Reply to this email directly or view it on GitHub.

Owner

etianen commented Aug 29, 2013

Many thanks... I appreciate it!

I've created a RTD account with username etianen .

I'll have a proper review of this when my current project is launched, which will be about a week. I'm really pepped about the new documentation, but I really don't have enough waking hours to give it a proper look-through at the moment. It's at the top of my "things to do when the damn site is launched" list. :P

Best,

Dave.

On 29 Aug 2013, at 10:59, pquentin notifications@github.com wrote:

Thanks! I've pushed my changes: 98e7cf4. Most of the work was changing `to``, changing```python to ::, and headers formatting. Please remove my push access, I don't need it anymore.

Here is the URL for the docs: https://django-reversion.readthedocs.org/en/latest/

You can create a RTD account, which will allow me to set you as the RTL maintainer. Once that's done, you'll be able to remove me from the maintainers list.

If you are happy with the conversion, feel free to close the issue!


Reply to this email directly or view it on GitHub.

@pquentin

This comment has been minimized.

Show comment
Hide comment
@pquentin

pquentin Aug 30, 2013

Contributor

No worries, I understand!

(You're now a maintainer of the RTD project. I can't remove myself.)

Contributor

pquentin commented Aug 30, 2013

No worries, I understand!

(You're now a maintainer of the RTD project. I can't remove myself.)

@etianen

This comment has been minimized.

Show comment
Hide comment
@etianen

etianen Sep 8, 2013

Owner

Hi,

Just in case you missed it, I had a proper look at your documentation work
today, made a couple of minor tweaks, then announced it on the
django-reversion mailing list to much fanfair. Thanks!

I've replaced all the existing wiki pages with links to their new locations
on RTD.

If you're still keen on improving the getting started guide, then please do
go ahead with pull requests. Otherwise, thanks for all your work on this.
django-reversion is looking pretty damn sweet!
On 30 Aug 2013 07:12, "pquentin" notifications@github.com wrote:

No worries, I understand!

(You're now a maintainer of the RTD project. I can't remove myself.)


Reply to this email directly or view it on GitHubhttps://github.com//issues/250#issuecomment-23542411
.

Owner

etianen commented Sep 8, 2013

Hi,

Just in case you missed it, I had a proper look at your documentation work
today, made a couple of minor tweaks, then announced it on the
django-reversion mailing list to much fanfair. Thanks!

I've replaced all the existing wiki pages with links to their new locations
on RTD.

If you're still keen on improving the getting started guide, then please do
go ahead with pull requests. Otherwise, thanks for all your work on this.
django-reversion is looking pretty damn sweet!
On 30 Aug 2013 07:12, "pquentin" notifications@github.com wrote:

No worries, I understand!

(You're now a maintainer of the RTD project. I can't remove myself.)


Reply to this email directly or view it on GitHubhttps://github.com//issues/250#issuecomment-23542411
.

@pquentin

This comment has been minimized.

Show comment
Hide comment
@pquentin

pquentin Sep 9, 2013

Contributor

Nice! I'm now subscribed to the mailing list, I had indeed missed this. The tweaks are not that minor and make the docs even better, congrats! :) I'll see what I can do in the next few days. Thanks. :)

Contributor

pquentin commented Sep 9, 2013

Nice! I'm now subscribed to the mailing list, I had indeed missed this. The tweaks are not that minor and make the docs even better, congrats! :) I'll see what I can do in the next few days. Thanks. :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment