Adding context to docs

[Diana Probst]

I've been struggling to add forms to an app I am building, because the context of where to put form classes is missing in the docs.  I don't want to take a guess, even if it's right, when I could be following best practice.  In the 1.7 tutorial, the namespacing and file naming is laid out pretty simply, but in the Working with Forms page, https://docs.djangoproject.com/en/1.7/topics/forms/ which is the start of the overview, there is nothing setting out that I should, say, be using /myapp/forms.py .  I think that would be a valuable thing to add to the docs.  I've searched for where else it might be, and I can't find it, so even if it does exist elsewhere, the difficulty of finding this information is high.

The tutorials have the name of file at the top of each example, which is my favourite solution, but even a briefing at the top of the forms overview would be an improvement on what is currently a low information zone.  Currently, I don't have access to info on how to namespace my forms, and where to create what I'm creating.  It's a small change that would make the docs clearer and easier to use.

DP

[Curtis Maloney]

In all cases in Django, if your code imports the class, you can put it wherever you like - so long as Python can find it.  It's only things that are "discovered" by Django [admin, models, etc] that must be in a specific module.

By convention, forms are put into forms.py ... but that's so _humans_ will know where to look.

That said, it certainly would be a good thing for the tutorial to explain this, and for the forms docs to recommend using "mapp/forms.py".

Do you feel up to writing a patch and making a PR?

--

Curtis

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/f5a8e89f-d9d8-46a3-95b7-0b075c15fec4%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Diana Probst]

Never done either of those things, and I'm completely not set up to do them. I will if creating this subject has made me the owner of it, but it's a lot more work for me than it would be for someone else. I'd start with the Writing your First Django Patch part of the tutorial, yes?

Thanks for the explanation. I had a form in what I was pretty sure was the wrong place, and it was working, but it rankled so hard I had to look for why.

[Curtis Maloney]

On 20 February 2015 at 11:49, Diana Probst <dianac...@googlemail.com> wrote:

Never done either of those things, and I'm completely not set up to do them.  I will if creating this subject has made me the owner of it, but it's a lot more work for me than it would be for someone else.  I'd start with the Writing your First Django Patch part of the tutorial, yes?

Please don't feel pressured to write a patch to get this fixed.  If you don't feel up to it, or don't have the time, I'm happy to do it - albeit at my own pace.

I prefer to suggest people submit PRs simply to reinforce the fact that anyone is welcome to contribute.

I highly recommend reading the contribution guide - https://docs.djangoproject.com/en/1.7/internals/contributing/

If you'd like some guidance on getting set up to make PRs, come find the helpful folks on IRC, in #django on the freenode network.

Thanks for the explanation.  I had a form in what I was pretty sure was the wrong place, and it was working, but it rankled so hard I had to look for why.

That's usually a sign of good instincts :)

If code doesn't "feel" right, it often leads to problems down the line.

--

Curtis

[Chris Foresman]

Diana,

I've been working on my own first patches to Django. I'm available all day tomorrow from about 8-5:30 CST if you want any help with the basic steps. You'll basically want to fork django/django, git clone that to your local machine, and set the original repo as your upstream remote to get started. Then you can make a branch, make your changes, then open a pull request from your branch to upstream/master.

Some of the nice people in #djnago-devs on freenode have been helping me along the way; I'll be there tomorrow, too.

Good luck!

[Diana Probst]

The last time I logged into GitHub was at least one computer ago. And that computer blew up a bit. I'll try to get on, but this is contingent on many factors, and I don't have control over them all. What I will do is read the docs on contributing.

Thanks for the time, both/all of you. Django is damned cool, and it's great to peek behind the curtain.

[Russell Keith-Magee]

On Fri, Feb 20, 2015 at 9:29 AM, Diana Probst <dianac...@googlemail.com> wrote:

The last time I logged into GitHub was at least one computer ago.  And that computer blew up a bit.  I'll try to get on, but this is contingent on many factors, and I don't have control over them all.  What I will do is read the docs on contributing.

Thanks for the time, both/all of you.  Django is damned cool, and it's great to peek behind the curtain.

Since you're a fan, and your Google profile (and email address) suggests you're based in Cambridge (the English one), I'll take this opportunity to plug DjangoCon Europe. 

http://2015.djangocon.eu 

It's being held in Cardiff from 31 May-5 June this year, and as well as talks at varying levels of technical depth, there will be a number of events designed to encourage people to make the transition from enthusiastic user to contributor - most notably, the "Don't be afraid to commit" workshop for people who are potentially interested in contributing, but don't know where to start.

http://2015.djangocon.eu/event/dont-be-afraid-commit/

Yours,

Russ Magee %-)