[py-svn] r7086 - py/dist/doc
hpk at codespeak.net
hpk at codespeak.net
Fri Oct 22 00:43:20 CEST 2004
Author: hpk
Date: Fri Oct 22 00:43:19 2004
New Revision: 7086
Modified:
py/dist/doc/why_py.txt
Log:
- explained a possible upcoming release policy,
at least my idea of it. It relies and defines
everything by virtue of automated tests.
- inserted a reference to the jorendorff path.py
implementation which people keep refering me to.
Modified: py/dist/doc/why_py.txt
==============================================================================
--- py/dist/doc/why_py.txt (original)
+++ py/dist/doc/why_py.txt Fri Oct 22 00:43:19 2004
@@ -69,6 +69,9 @@
What is the py libs current focus?
==================================
+testing testing testing
+-----------------------
+
Currently, the main focus of the py lib is to get a decent
`test environment`_, indeed to produce the best one out there.
Writing, distributing and deploying tests should become
@@ -79,39 +82,100 @@
cycles. Automated tests are a means of communication
as well.
-Most importantly, we try to allow test scripts with minimal
-boilerplate code or no boilerplate at all. With the py lib
-you can simply use ``assert`` statements in order to - well -
-assert something about objects in your code. No
-``assertEqual(s)`` and all the other kinds of funny names
-which only cover part of what you want to assert about an
-expression, anyway.
+We try to allow test scripts with minimal boilerplate code or
+no boilerplate at all. With the py lib you can simply use
+``assert`` statements in order to - well - assert something
+about objects in your code. No ``assertEqual(s)`` and all the
+other kinds of funny names which only cover part of what you
+want to assert about an expression, anyway.
+
+allowing maximum refactoring in the future ...
+----------------------------------------------
+
+explicit name export control
+............................
In order, to allow a fast development pace across versions of
the py lib there is **explicit name export control**. You
will only see names which make sense to use from the outside
-and which the py lib developers want to guarantee across major
-versions.
-
-No *tested feature* of the exported `py API`_ will
-vanish across major releases until it is marked deprecated.
-But if deprecated an API could go with every following major
-release. Indeed, much thought is given to reduce the exported
-*name complexity*. This is an area where the python "batteries"
-lack a lot. They expose so many names that it becomes very
-hard to change APIs across releases. This kills the fun of
-refactoring and improving things.
-
-Another focus are well tested *Path* implementations that
-allow to seemlessly work with different backends, currently
-a local filesystem and subversion working copies and subversion
-remote URLs. Moreover, it provides an experimental ``extpy``
-path to address a Python object on a possibly remote filesystem.
+and which the py lib developers want to guarantee across multiple
+revisions. However, you don't need to treat the ``py`` lib as
+anything special. You can simply use the usual ``import``
+statement and will not notice much of a difference - except that
+the namespaces you'll see from the ``py`` lib will be extreamly
+clean and have no clutter.
+
+Indeed, much thought is given to reduce the exported *name
+complexity*. This is an area where the python "batteries" and
+many python packages unfortunately lack a lot. They expose so
+many names that it becomes very hard to change APIs across
+releases. People have been adding whole interface systems
+because of that but arguably this adds another layer of names
+instead of reducing the original problem.
+
+Anyway, exporting to many names kills the fun of refactoring
+and improving things. We want to avoid that as much as
+possible.
+
+Upcoming Release policy & API guarantees
+........................................
+
+We'll talk about major, minor and micro numbers as the three
+numbers in "1.2.3" respectively. These are the (draft!)
+release policies:
+
+- Micro-releases are bug fix releases and may not introduce
+ new names to the public API. They may add tests and thus
+ further define the behaviour of the py lib. They may
+ completly change the implementation but the public API
+ tests will continue to run.
+
+- No **tested feature** of the exported `py API`_ is to vanish
+ across minor releases until it is marked deprecated.
+
+ For example, pure API tests of a future version 1.0 are to
+ continue to fully run on 1.1 and so on. If an API gets
+ deprecated with a minor release it goes with the next minor
+ release. Thus if you don't use deprecated APIs you should
+ be able to use the next two minor releases. However, if
+ you relied on some untested implementation behaviour,
+ you may still get screwed. Solution: add API tests to the
+ py lib :-) It's really the tests that make the difference.
+
+- Pure API tests are not allowed to access any implementation
+ level details. For example, accessing names starting with
+ a single leading '_' is generally seen as an implementation
+ level detail.
+
+- we intend to involve expert developers who give new APIs an
+ independent review before they go into a minor release
+ and even more so before they go into a major release.
+
+- major releases *should*, but are not required to, pass
+ all API tests of the previous latest major released
+ version. A full list of changes is to be included in
+ the release notes, including the tests that got abandoned.
+
+the need to find the right *paths* ...
+--------------------------------------
+
+Another focus are well tested so called *path* implementations
+that allow you to seemlessly work with different backends,
+currently a local filesystem, subversion working copies and
+subversion remote URLs. Moreover, there is an experimental
+``extpy`` path to address a Python object on the (possibly
+remote) filesystem. The `jorendorff path.py`_ implementation
+goes somewhat in the same direction but doesn't try to
+systematically access local and remote file systems as well as
+other hierarchic namespaces. The latter is the focus of the
+``py.path`` API.
If you are ready to grasp more then you may try reading
about future_ coding goals of the py lib, which reflect the
current developers thoughts and discussions.
+.. _`jorendorff path.py`: http://www.jorendorff.com/articles/python/path/
+
How does py development work?
=============================
@@ -121,10 +185,12 @@
We are discussing things on our `py-dev mailing list`_
and collaborate via the codespeak subversion repository.
-We follow a `coding style`_ which builds on `PEP 8`_, the basic
-python coding style document. It's easy to get commit rights
-especially if you are an experienced python developer
-and share some of the frustrations described above.
+We follow a `coding style`_ which strongly builds on `PEP 8`_,
+the basic python coding style document.
+
+It's easy to get commit rights especially if you are an
+experienced python developer and share some of the
+frustrations described above.
Moreover, the world will be granted svn commit rights to all
py test files so that you can easily add bug-tests or tests
@@ -135,12 +201,11 @@
follow the `py-dev mailing list`_ and grasp some of the things
that are going on in the `future`_ book.
-
Licensing, please
-----------------
-Oh right, and you should also agree to release your code under
-an ``MIT license`` and consequently any other OSI-approved
+Oh right, and you should also agree to release your contributions
+under an ``MIT license`` and consequently any other OSI-approved
license. This is FOSS [#]_ and we want to have the py lib interopable
with whatever license style you prefer. Copyright generally
stays with the contributors. We are following the
@@ -156,8 +221,10 @@
---------------------------------
Some of the motivation for writing the py lib stems from needs
-during PyPy_ development, most notably testing and
-file system access issues.
+during PyPy_ development, most importantly testing and
+file system access issues. PyPy puts a lot of pressure
+on a testing environment and thus is a great **reality test**
+kind of thing.
More importantly, the development perspective taken from the
PyPy developers has some influence. For example, the
@@ -169,10 +236,10 @@
Who is "we"? Some history ...
=============================
-Some of the initial code was written from *Jens-Uwe Mager*
-and *Holger Krekel*, after which Holger continued on a previous
-incarnation of the py.test tool (known first as 'utest', then as
-'std.utest', now, finally and at last 'py.test').
+Some initial code was written from *Jens-Uwe Mager* and *Holger
+Krekel*, after which Holger continued on a previous
+incarnation of the py.test tool (known first as 'utest', then
+as 'std.utest', now, finally and at last 'py.test').
Helpful discussions took place with *Martijn Faassen*, *Stephan
Schwarzer* and then *Armin Rigo* who contributed important parts.
More information about the pytest-commit
mailing list