Reworking the Quick Start

[Kevin Teague]

I'd like to do some contributions to this project.

I've started by at the beginning, with the QuickStart, since I noticed
it was "cheating" and made quick by skipping some essential details.
I've filled it out some more, but also cut back the scope of the
initial project (and perhaps it could be trimmed back even a bit more,
which might make it a bit "quicker").

I've got a fork here where my contributions can be pulled from:

https://bitbucket.org/wheat/hitchhiker-guide-packaging


--
Subscription settings: http://groups.google.com/group/packaging-guide/subscribe?hl=en

[Tarek Ziadé]

On Sun, Apr 25, 2010 at 1:30 AM, Kevin Teague <ke...@bud.ca> wrote:
> I'd like to do some contributions to this project.

Hi Kevin,

Great ! Welcome aboard

>
> I've started by at the beginning, with the QuickStart, since I noticed
> it was "cheating" and made quick by skipping some essential details.
> I've filled it out some more, but also cut back the scope of the
> initial project (and perhaps it could be trimmed back even a bit more,
> which might make it a bit "quicker").
>
> I've got a fork here where my contributions can be pulled from:
>
> https://bitbucket.org/wheat/hitchhiker-guide-packaging

I have adding you an access to the repo. Go ahead and merge it.
Just make sure the reSt builds before you commit, since
guide.python-distribute.org
is generated once per hour with the repo


Cheers,
Tarej

>
>
> --
> Subscription settings: http://groups.google.com/group/packaging-guide/subscribe?hl=en
>

--
Tarek Ziadé | http://ziade.org

[anatoly techtonik]

On Apr 25, 2:30 am, Kevin Teague <ke...@bud.ca> wrote:
> I've started by at the beginning, with the QuickStart, since I noticed
> it was "cheating" and made quick by skipping some essential details.

It may become slow start if the amount of text exceeds a reasonable
amount of time to read this stuff (to say 15 minutes).

> I've filled it out some more, but also cut back the scope of the
> initial project (and perhaps it could be trimmed back even a bit more,
> which might make it a bit "quicker").

Have you tested the new version of QuickStart from the scratch? I am
asking, because in your commit https://bitbucket.org/wheat/hitchhiker-guide-packaging/changeset/edfa1f74fbc9
you've inserted `setup.py` sample with the following contents::

setup(
name='TowelStuff',
version='0.1dev',
packages=['towelstuff',],
license='Creative Commons Attribution-Noncommercial-Share
Alike license',
long_description=open('README.txt').read(),
)

The README.txt open call will fail on `setup.py` according to later
paragraph that says::

You will also notice that the README.txt and LICENSE.txt files are
not
included as part of distribution - unless those files have checked
into
Subversion.

It is common to make `svn export` before releasing projects to avoid
bundling .svn dirs, so README.txt is unlikely to trap inside. The
whole statement about SVN handling is doubtful. Does distutils really
rely on Subversion to determine files to be packages? Does it require
SVN client installed or SVN bindings or meddle with working copy
directory directly?

To make quick start testing easier there could be an accompanying
public domain example/testing/boilerplate package with sources somehow
synced to the guide.
--
anatoly t.

[Kevin Teague]

On May 3, 12:34 am, anatoly techtonik <techto...@gmail.com> wrote:

> It is common to make `svn export` before releasing projects to avoid
> bundling .svn dirs, so README.txt is unlikely to trap inside. The
> whole statement about SVN handling is doubtful. Does distutils really
> rely on Subversion to determine files to be packages? Does it require
> SVN client installed or SVN bindings or meddle with working copy
> directory directly?

No, I included misinformation in the guide :(

Only Setuptools/Distribute use SVN to determine the MANIFEST, AFAIK.
I've
just re-written that section. The Quickstart still feels "clunky" to
me,
but at least it's more correct than it used to be ...

I left a TO-DO to link to docs describing how to include files in a
MANIFEST.
Is the intention of the Guide to replace the Distutils docs
completely, or
will they still be maintained and we should be linking to them?

http://docs.python.org/distutils/sourcedist.html

There are some edits we could do there, such as, "README.txt (or
README),
setup.py (or whatever you called your setup script), and setup.cfg".
Can you really call your 'setup.py' script whatever you want? I'm
pretty
sure pip, easy_install, etc. won't work if you rename them ...

> To make quick start testing easier there could be an accompanying
> public domain example/testing/boilerplate package with sources somehow
> synced to the guide.

Yes. A job for another day though ...

[Tarek Ziadé]

On Wed, May 5, 2010 at 2:03 AM, Kevin Teague <ke...@bud.ca> wrote:
>
>
> On May 3, 12:34 am, anatoly techtonik <techto...@gmail.com> wrote:
>
>> It is common to make `svn export` before releasing projects to avoid
>> bundling .svn dirs, so README.txt is unlikely to trap inside. The
>> whole statement about SVN handling is doubtful. Does distutils really
>> rely on Subversion to determine files to be packages? Does it require
>> SVN client installed or SVN bindings or meddle with working copy
>> directory directly?
>
> No, I included misinformation in the guide :(
>
> Only Setuptools/Distribute use SVN to determine the MANIFEST, AFAIK.
> I've
> just re-written that section. The Quickstart still feels "clunky" to
> me,
> but at least it's more correct than it used to be ...

I consider using the SVN to determine the file list as a bad practice,
because someone
that gets the source code is unable to re-run distutils commands
again, unless the .svn is included
in the source, which is even worse.

>
> I left a TO-DO to link to docs describing how to include files in a
> MANIFEST.
> Is the intention of the Guide to replace the Distutils docs
> completely, or
> will they still be maintained and we should be linking to them?
>
> http://docs.python.org/distutils/sourcedist.html

Yes, well, when distutils2 will be released, that might change. But
until then I guess it's ok

>
> There are some edits we could do there, such as, "README.txt (or
> README),
> setup.py (or whatever you called your setup script), and setup.cfg".
> Can you really call your 'setup.py' script whatever you want? I'm
> pretty
> sure pip, easy_install, etc. won't work if you rename them ...

Yes, it needs to be called setup.py

>
>> To make quick start testing easier there could be an accompanying
>> public domain example/testing/boilerplate package with sources somehow
>> synced to the guide.
>
> Yes. A job for another day though ...
>

Thanks for your contributions so far ! :)