#16779 - a tutorial for first time Django contributors

[Tim Graham]

Taavi Taijala has written a tutorial for new contributors that I've given an initial review.  I'm hoping we can get a few more sets of eyes on it.  Might be useful to pass it on to any newbies you know and have them try it out as well.  Thanks!

https://code.djangoproject.com/ticket/16779

[Tim Graham]

Thanks to those who have weighed in on this thus far. I've rewritten part of the tutorial to use a more recent ticket from the "git era" to hopefully make things less confusing.

I think the part that has the most potential to confuse new contributors is the introduction of PYTHONPATH.  Claude suggested we could simply instruct users to run the tests like so:

PYTHONPATH=/path/to/django ./run_tests.py --settings=test_sqlite

I'm not particularly in love with that, but it would eliminate the need to try to explain things and perhaps we could link out to an external resource that explains PYTHONPATH well, although I haven't found anything after a quick search.

Any specific feedback on this paragraph, or the tutorial as whole, would be appreciated:

http://techytim.com/django/16779/intro/contributing.html#setting-django-up-to-run-the-test-suite

[Shai Berger]

On Sunday 11 November 2012, Tim Graham wrote:
>
> I think the part that has the most potential to confuse new contributors is
> the introduction of PYTHONPATH. Claude suggested we could simply instruct
> users to run the tests like so:
>
> PYTHONPATH=/path/to/django ./run_tests.py --settings=test_sqlite
>
> I'm not particularly in love with that, but it would eliminate the need to
> try to explain things

It would leave a lot to explain to Windows users (which I note you are still
trying to cater for).

Shai.

[Aymeric Augustin]

Le 11 nov. 2012 à 06:53, Shai Berger <sh...@platonix.com> a écrit :

> On Sunday 11 November 2012, Tim Graham wrote:
>>
>> I think the part that has the most potential to confuse new contributors is
>> the introduction of PYTHONPATH. Claude suggested we could simply instruct
>> users to run the tests like so:
>>
>> PYTHONPATH=/path/to/django ./run_tests.py --settings=test_sqlite
>>
>> I'm not particularly in love with that, but it would eliminate the need to
>> try to explain things

I've always been running the tests with:

$ cd tests
$ PYTHONPATH=.. pythonX.Y runtests.py --settings=test_<xxx>

It's straightforward and easy to understand: "Python will look for django in the parent directory".

If you're just running Django's test suite on a reasonably configured system, you're starting with an empty PYTHONPATH; you don't really need PYTHONPATH=..:$PYTHONPATH.

The alternatives are:
- either prone to mistakes and side effects (setting a systemwide PYTHONPATH — what if I move my checkout?);
- or even more complicated to explain (mkvirtualenv djang && pip install -e .)

> It would leave a lot to explain to Windows users (which I note you are still
> trying to cater for).

If you're using the default options of the git installer on Windows, you're getting a fairly decent environment (MINGW32). It creates a "Git Bash" icon on the desktop, which starts a Bash shell where `git` works. After adding `export PATH=/c/Python27:$PATH` to `~/.bashrc`, `python` also works in that shell.

If we tell Windows users to use "Git Bash", we can skip most of the Windows-specific instructions. It's likely to make the tutorial a better experience for them.

Otherwise, `set PYTHONPATH=..` works in `cmd.exe`, but I can't recommend `cmd.exe` with a straight face :/

--
Aymeric.

[william ratcliff]

I develop on windows, linux, and macos--for windows, I have to say that I tend to use tortoise-git (somehow, I still prefer it to github for windows), whereas for linux, the command line is great....From my experience leaping between platforms, it's rather painful to try to shoehorn the way of doing things on one platform into another...It's more work, but perhaps a linux/windows section would work best for those areas that are more platform specific (for example, environment variables in windows, vs linux)?

Anywho, just my 2 cents...

--
You received this message because you are subscribed to the Google Groups "Django developers" group.
To post to this group, send email to django-d...@googlegroups.com.
To unsubscribe from this group, send email to django-develop...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.

[william ratcliff]

And I should say, thanks for the effort on this!

[Daniele Procida]

On Sat, Nov 10, 2012, Tim Graham <timog...@gmail.com> wrote:

>Any specific feedback on this paragraph, or the tutorial as whole, would be
>appreciated:

My four thoughts:

Firstly: I like to see things like:

./runtests.py --settings=test_sqlite

include a comment when appropriate; in this case to say why we are using --settings=test_sqlite

Secondly: "For advanced users who wish to use virtualenv" - is this really implying that only advanced users would use virtualenv?

I think that the most helpful thing to say to people who are not using virtualenv already is that they need spend 15 minutes learning to use it before they do anything else, because it's one of the most valuable and easy to learn tools they will ever encounter.

Thirdly: if everyone is using virtualenv, would that eliminate the difficulties trying to explain PYTHONPATH?

Fourthly: although this and the Working with Git and GitHub tutorial explain the technical part of the process well, they both somewhat assume that you're able to come up with complete if not perfect patch.

In reality I think a lot of back-and-forth refinement goes on before that point is reached - what would be handy is advice on how to proceed when your patch is incomplete and you need some feedback before going further.

But this looks great, I wish I had read it myself before trying to submit anything.

Daniele

[Tim Graham]

Thanks for the feedback everyone.  I'm made some updates based on these suggestions, please see the ticket:

https://code.djangoproject.com/ticket/16779