classification
Title: Add "Quick Start" section to the devguide index
Type: Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: brian.curtin, eric.araujo, ezio.melotti, ned.deily, pitrou, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2011-10-19 23:37 by ezio.melotti, last changed 2011-10-23 23:31 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
quickstart.diff ezio.melotti, 2011-10-19 23:37
issue13228.diff ezio.melotti, 2011-10-21 16:22
issue13228-2.diff ezio.melotti, 2011-10-21 16:54
issue13228-3.diff ezio.melotti, 2011-10-23 23:09
Messages (11)
msg145993 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-19 23:37
Attached patch adds to the index page a list of 5 steps necessary to set up Python and make a patch.  These informations are currently scattered around a few pages and many contributors are already familiar with Mercurial and the process of creating patches, so they just need to know the address where to clone and the commands to compile Python and run the tests.
The list also includes links to the other sections, so users can find more detailed information if they need them (this is also valid for the second point: the "configure" command is specific to Unix, but the link has information about Windows too).
All this should make the devguide a bit more usable.

(A bit of background: during the sprints at PyCon FI I wrote the steps 1-3 on the whiteboard, and they worked well for everyone.  Most of them managed to get something done with no further assistance, even if a few people were not so familiar with Mercurial.)
msg146081 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-21 13:33
+   ``hg clone http://hg.python.org/cpython``;
I use http://hg.python.org/cpython#default to avoid cloning the 2.x branches, that’s an optimization that can save some time and space.

+2. run ``./configure --with-pydebug && make -j2``
Is make -j2 harmless on single-CPU systems?  Doesn’t our make default to -j0 anyway, to use all CPUs?

+3. :doc:`run the tests <runtests>` with ``./python -m test``;
Is that cross-platform?  Mac OS X has python.exe for example.
msg146096 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-21 15:39
> +   ``hg clone http://hg.python.org/cpython``;
> I use http://hg.python.org/cpython#default to avoid cloning the 2.x 
> branches, that’s an optimization that can save some time and space.

I think in the default case it's easier to get'em all.

> +2. run ``./configure --with-pydebug && make -j2``
> Is make -j2 harmless on single-CPU systems?  Doesn’t our make default 
> to -j0 anyway, to use all CPUs?

As far as I know, -j2 is harmless on single-CPU systems, but I don't think we use all the CPUs by default with a plain `make`.

> +3. :doc:`run the tests <runtests>` with ``./python -m test``;
> Is that cross-platform?  Mac OS X has python.exe for example.

These instructions are a bit UNIX/Linux-centric, because that's what most developers seems to use.  On Mac OS it would indeed be ./python.exe, but it shouldn't take long for the developers to figure that out or click on the link and see how it works for their OS.

If you think it's worth to expand a bit, I guess we could still do it.
msg146101 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-10-21 16:16
You could replace "python -m test" with "make test", although it only does the right thing in 3.3.
Otherwise, "python -m test -j3" would be friendlier to the reader I think :)

+1 on the principle, by the way!
msg146102 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-21 16:22
New patch that adds a few more instructions for Windows/Mac OS.  `make test` is UNIX-specific, so I left `./python -m test`.
I also moved the section before the quick links, since it seems to me more interesting that those links (you don't usually want to start from the PEPs or the buildbot page).
msg146103 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-10-21 16:26
> New patch that adds a few more instructions for Windows/Mac OS.  `make
> test` is UNIX-specific, so I left `./python -m test`.
> I also moved the section before the quick links, since it seems to me
> more interesting that those links (you don't usually want to start
> from the PEPs or the buildbot page).

You want at the minimum "python -m test -j3", I think (many tests don't
really use the CPU).
Your Windows instructions could be improved a bit:
- not "the project files from the PCbuild" directory, but
"PCbuild/pcbuild.sln" (there are many project files)
- not "python.exe", but "PCbuild\python_d.exe"
msg146104 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-21 16:54
Thanks for the feedback, here's an updated patch.
msg146125 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2011-10-21 19:56
"./python.exe" is not a given on Mac OS X; that's only true if the file system you are building in is case-insensitive, otherwise it is "./python".  Suggest rewording to:

   "(you may need to use :file:`./python.exe` on Mac OS X" ...
msg146269 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-23 23:09
That's a good point, but I find the wording a bit long.  The attached patch tries to keep it short and adds a link to the section that explains when and why it's python.exe.
msg146270 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-10-23 23:30
New changeset 25f1c003ea01 by Ezio Melotti in branch 'default':
#13228: add a "Quick Start" section to the index page.
http://hg.python.org/devguide/rev/25f1c003ea01
msg146271 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-23 23:31
Done, thanks for the feedback!
History
Date User Action Args
2011-10-23 23:31:52ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg146271

stage: commit review -> resolved
2011-10-23 23:30:43python-devsetnosy: + python-dev
messages: + msg146270
2011-10-23 23:09:59ezio.melottisetfiles: + issue13228-3.diff

messages: + msg146269
2011-10-21 19:56:46ned.deilysetnosy: + ned.deily
messages: + msg146125
2011-10-21 16:54:25ezio.melottisetfiles: + issue13228-2.diff
nosy: + brian.curtin
messages: + msg146104

2011-10-21 16:26:31pitrousetmessages: + msg146103
2011-10-21 16:22:24ezio.melottisetfiles: + issue13228.diff

messages: + msg146102
2011-10-21 16:16:02pitrousetnosy: + pitrou
messages: + msg146101
2011-10-21 15:39:56ezio.melottisetmessages: + msg146096
2011-10-21 13:33:19eric.araujosetmessages: + msg146081
2011-10-19 23:37:02ezio.melotticreate