From 526241ce94c3d38555914430b9888a8ee0f0ea55 Mon Sep 17 00:00:00 2001 From: alvy Date: Thu, 15 Oct 2020 15:17:38 -0400 Subject: group development related files together --- docs/developer-guide.rst | 130 ----------------------------------- docs/development.rst | 35 ---------- docs/development/developer-guide.rst | 130 +++++++++++++++++++++++++++++++++++ docs/development/history.rst | 45 ++++++++++++ docs/development/index.rst | 36 ++++++++++ docs/development/releases.rst | 37 ++++++++++ docs/history.rst | 45 ------------ docs/index.rst | 2 +- docs/releases.rst | 37 ---------- 9 files changed, 249 insertions(+), 248 deletions(-) delete mode 100644 docs/developer-guide.rst delete mode 100644 docs/development.rst create mode 100644 docs/development/developer-guide.rst create mode 100644 docs/development/history.rst create mode 100644 docs/development/index.rst create mode 100644 docs/development/releases.rst delete mode 100644 docs/history.rst delete mode 100644 docs/releases.rst (limited to 'docs') diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst deleted file mode 100644 index d2366931..00000000 --- a/docs/developer-guide.rst +++ /dev/null @@ -1,130 +0,0 @@ -================================ -Developer's Guide for Setuptools -================================ - -If you want to know more about contributing on Setuptools, this is the place. - - -.. contents:: **Table of Contents** - - -------------------- -Recommended Reading -------------------- - -Please read `How to write the perfect pull request -`_ for some tips -on contributing to open source projects. Although the article is not -authoritative, it was authored by the maintainer of Setuptools, so reflects -his opinions and will improve the likelihood of acceptance and quality of -contribution. - ------------------- -Project Management ------------------- - -Setuptools is maintained primarily in GitHub at `this home -`_. Setuptools is maintained under the -Python Packaging Authority (PyPA) with several core contributors. All bugs -for Setuptools are filed and the canonical source is maintained in GitHub. - -User support and discussions are done through the issue tracker (for specific) -issues, through the `distutils-sig mailing list `_, or on IRC (Freenode) at -#pypa. - -Discussions about development happen on the distutils-sig mailing list or on -`Gitter `_. - ------------------ -Authoring Tickets ------------------ - -Before authoring any source code, it's often prudent to file a ticket -describing the motivation behind making changes. First search to see if a -ticket already exists for your issue. If not, create one. Try to think from -the perspective of the reader. Explain what behavior you expected, what you -got instead, and what factors might have contributed to the unexpected -behavior. In GitHub, surround a block of code or traceback with the triple -backtick "\`\`\`" so that it is formatted nicely. - -Filing a ticket provides a forum for justification, discussion, and -clarification. The ticket provides a record of the purpose for the change and -any hard decisions that were made. It provides a single place for others to -reference when trying to understand why the software operates the way it does -or why certain changes were made. - -Setuptools makes extensive use of hyperlinks to tickets in the changelog so -that system integrators and other users can get a quick summary, but then -jump to the in-depth discussion about any subject referenced. - ---------------------- -Making a pull request ---------------------- - -When making a pull request, please -:ref:`include a short summary of the changes ` and a reference to any issue tickets that the PR is -intended to solve. -All PRs with code changes should include tests. All changes should -include a changelog entry. - -.. include:: ../changelog.d/README.rst - -------------------- -Auto-Merge Requests -------------------- - -To support running all code through CI, even lightweight contributions, -the project employs Mergify to auto-merge pull requests tagged as -auto-merge. - -Use ``hub pull-request -l auto-merge`` to create such a pull request -from the command line after pushing a new branch. - -------- -Testing -------- - -The primary tests are run using tox. Make sure you have tox installed, -and invoke it:: - - $ tox - -Under continuous integration, additional tests may be run. See the -``.travis.yml`` file for full details on the tests run under Travis-CI. - -------------------- -Semantic Versioning -------------------- - -Setuptools follows ``semver``. - -.. explain value of reflecting meaning in versions. - ----------------------- -Building Documentation ----------------------- - -Setuptools relies on the `Sphinx`_ system for building documentation. -The `published documentation`_ is hosted on Read the Docs. - -To build the docs locally, use tox:: - - $ tox -e docs - -.. _Sphinx: http://www.sphinx-doc.org/en/master/ -.. _published documentation: https://setuptools.readthedocs.io/en/latest/ - ---------------------- -Vendored Dependencies ---------------------- - -Setuptools has some dependencies, but due to `bootstrapping issues -`_, those dependencies -cannot be declared as they won't be resolved soon enough to build -setuptools from source. Eventually, this limitation may be lifted as -PEP 517/518 reach ubiquitous adoption, but for now, Setuptools -cannot declare dependencies other than through -``setuptools/_vendor/vendored.txt`` and -``pkg_resources/_vendor/vendored.txt`` and refreshed by way of -``paver update_vendored`` (pavement.py). diff --git a/docs/development.rst b/docs/development.rst deleted file mode 100644 index 28e653fe..00000000 --- a/docs/development.rst +++ /dev/null @@ -1,35 +0,0 @@ -------------------------- -Development on Setuptools -------------------------- - -Setuptools is maintained by the Python community under the Python Packaging -Authority (PyPA) and led by Jason R. Coombs. - -This document describes the process by which Setuptools is developed. -This document assumes the reader has some passing familiarity with -*using* setuptools, the ``pkg_resources`` module, and pip. It -does not attempt to explain basic concepts like inter-project -dependencies, nor does it contain detailed lexical syntax for most -file formats. Neither does it explain concepts like "namespace -packages" or "resources" in any detail, as all of these subjects are -covered at length in the setuptools developer's guide and the -``pkg_resources`` reference manual. - -Instead, this is **internal** documentation for how those concepts and -features are *implemented* in concrete terms. It is intended for people -who are working on the setuptools code base, who want to be able to -troubleshoot setuptools problems, want to write code that reads the file -formats involved, or want to otherwise tinker with setuptools-generated -files and directories. - -Note, however, that these are all internal implementation details and -are therefore subject to change; stick to the published API if you don't -want to be responsible for keeping your code from breaking when -setuptools changes. You have been warned. - -.. toctree:: - :maxdepth: 1 - - developer-guide - formats - releases diff --git a/docs/development/developer-guide.rst b/docs/development/developer-guide.rst new file mode 100644 index 00000000..d2366931 --- /dev/null +++ b/docs/development/developer-guide.rst @@ -0,0 +1,130 @@ +================================ +Developer's Guide for Setuptools +================================ + +If you want to know more about contributing on Setuptools, this is the place. + + +.. contents:: **Table of Contents** + + +------------------- +Recommended Reading +------------------- + +Please read `How to write the perfect pull request +`_ for some tips +on contributing to open source projects. Although the article is not +authoritative, it was authored by the maintainer of Setuptools, so reflects +his opinions and will improve the likelihood of acceptance and quality of +contribution. + +------------------ +Project Management +------------------ + +Setuptools is maintained primarily in GitHub at `this home +`_. Setuptools is maintained under the +Python Packaging Authority (PyPA) with several core contributors. All bugs +for Setuptools are filed and the canonical source is maintained in GitHub. + +User support and discussions are done through the issue tracker (for specific) +issues, through the `distutils-sig mailing list `_, or on IRC (Freenode) at +#pypa. + +Discussions about development happen on the distutils-sig mailing list or on +`Gitter `_. + +----------------- +Authoring Tickets +----------------- + +Before authoring any source code, it's often prudent to file a ticket +describing the motivation behind making changes. First search to see if a +ticket already exists for your issue. If not, create one. Try to think from +the perspective of the reader. Explain what behavior you expected, what you +got instead, and what factors might have contributed to the unexpected +behavior. In GitHub, surround a block of code or traceback with the triple +backtick "\`\`\`" so that it is formatted nicely. + +Filing a ticket provides a forum for justification, discussion, and +clarification. The ticket provides a record of the purpose for the change and +any hard decisions that were made. It provides a single place for others to +reference when trying to understand why the software operates the way it does +or why certain changes were made. + +Setuptools makes extensive use of hyperlinks to tickets in the changelog so +that system integrators and other users can get a quick summary, but then +jump to the in-depth discussion about any subject referenced. + +--------------------- +Making a pull request +--------------------- + +When making a pull request, please +:ref:`include a short summary of the changes ` and a reference to any issue tickets that the PR is +intended to solve. +All PRs with code changes should include tests. All changes should +include a changelog entry. + +.. include:: ../changelog.d/README.rst + +------------------- +Auto-Merge Requests +------------------- + +To support running all code through CI, even lightweight contributions, +the project employs Mergify to auto-merge pull requests tagged as +auto-merge. + +Use ``hub pull-request -l auto-merge`` to create such a pull request +from the command line after pushing a new branch. + +------- +Testing +------- + +The primary tests are run using tox. Make sure you have tox installed, +and invoke it:: + + $ tox + +Under continuous integration, additional tests may be run. See the +``.travis.yml`` file for full details on the tests run under Travis-CI. + +------------------- +Semantic Versioning +------------------- + +Setuptools follows ``semver``. + +.. explain value of reflecting meaning in versions. + +---------------------- +Building Documentation +---------------------- + +Setuptools relies on the `Sphinx`_ system for building documentation. +The `published documentation`_ is hosted on Read the Docs. + +To build the docs locally, use tox:: + + $ tox -e docs + +.. _Sphinx: http://www.sphinx-doc.org/en/master/ +.. _published documentation: https://setuptools.readthedocs.io/en/latest/ + +--------------------- +Vendored Dependencies +--------------------- + +Setuptools has some dependencies, but due to `bootstrapping issues +`_, those dependencies +cannot be declared as they won't be resolved soon enough to build +setuptools from source. Eventually, this limitation may be lifted as +PEP 517/518 reach ubiquitous adoption, but for now, Setuptools +cannot declare dependencies other than through +``setuptools/_vendor/vendored.txt`` and +``pkg_resources/_vendor/vendored.txt`` and refreshed by way of +``paver update_vendored`` (pavement.py). diff --git a/docs/development/history.rst b/docs/development/history.rst new file mode 100644 index 00000000..faf7adfe --- /dev/null +++ b/docs/development/history.rst @@ -0,0 +1,45 @@ +:tocdepth: 2 + +.. _changes: + +History +******* + +.. include:: ../CHANGES (links).rst + +Credits +******* + +* The original design for the ``.egg`` format and the ``pkg_resources`` API was + co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first + version of ``pkg_resources``, and supplied the macOS operating system version + compatibility algorithm. + +* Ian Bicking implemented many early "creature comfort" features of + easy_install, including support for downloading via Sourceforge and + Subversion repositories. Ian's comments on the Web-SIG about WSGI + application deployment also inspired the concept of "entry points" in eggs, + and he has given talks at PyCon and elsewhere to inform and educate the + community about eggs and setuptools. + +* Jim Fulton contributed time and effort to build automated tests of various + aspects of ``easy_install``, and supplied the doctests for the command-line + ``.exe`` wrappers on Windows. + +* Phillip J. Eby is the seminal author of setuptools, and + first proposed the idea of an importable binary distribution format for + Python application plug-ins. + +* Significant parts of the implementation of setuptools were funded by the Open + Source Applications Foundation, to provide a plug-in infrastructure for the + Chandler PIM application. In addition, many OSAF staffers (such as Mike + "Code Bear" Taylor) contributed their time and stress as guinea pigs for the + use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!) + +* Tarek Ziadé is the principal author of the Distribute fork, which + re-invigorated the community on the project, encouraged renewed innovation, + and addressed many defects. + +* Jason R. Coombs performed the merge with Distribute, maintaining the + project for several years in coordination with the Python Packaging + Authority (PyPA). diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 00000000..d71d4dfc --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,36 @@ +------------------------- +Development on Setuptools +------------------------- + +Setuptools is maintained by the Python community under the Python Packaging +Authority (PyPA) and led by Jason R. Coombs. + +This document describes the process by which Setuptools is developed. +This document assumes the reader has some passing familiarity with +*using* setuptools, the ``pkg_resources`` module, and pip. It +does not attempt to explain basic concepts like inter-project +dependencies, nor does it contain detailed lexical syntax for most +file formats. Neither does it explain concepts like "namespace +packages" or "resources" in any detail, as all of these subjects are +covered at length in the setuptools developer's guide and the +``pkg_resources`` reference manual. + +Instead, this is **internal** documentation for how those concepts and +features are *implemented* in concrete terms. It is intended for people +who are working on the setuptools code base, who want to be able to +troubleshoot setuptools problems, want to write code that reads the file +formats involved, or want to otherwise tinker with setuptools-generated +files and directories. + +Note, however, that these are all internal implementation details and +are therefore subject to change; stick to the published API if you don't +want to be responsible for keeping your code from breaking when +setuptools changes. You have been warned. + +.. toctree:: + :maxdepth: 1 + + developer-guide + formats + releases + history diff --git a/docs/development/releases.rst b/docs/development/releases.rst new file mode 100644 index 00000000..35b415c2 --- /dev/null +++ b/docs/development/releases.rst @@ -0,0 +1,37 @@ +=============== +Release Process +=============== + +In order to allow for rapid, predictable releases, Setuptools uses a +mechanical technique for releases, enacted on tagged commits by +continuous integration. + +To finalize a release, run ``tox -e finalize``, review, then push +the changes. + +If tests pass, the release will be uploaded to PyPI. + +Release Frequency +----------------- + +Some have asked why Setuptools is released so frequently. Because Setuptools +uses a mechanical release process, it's very easy to make releases whenever the +code is stable (tests are passing). As a result, the philosophy is to release +early and often. + +While some find the frequent releases somewhat surprising, they only empower +the user. Although releases are made frequently, users can choose the frequency +at which they use those releases. If instead Setuptools contributions were only +released in batches, the user would be constrained to only use Setuptools when +those official releases were made. With frequent releases, the user can govern +exactly how often he wishes to update. + +Frequent releases also then obviate the need for dev or beta releases in most +cases. Because releases are made early and often, bugs are discovered and +corrected quickly, in many cases before other users have yet to encounter them. + +Release Managers +---------------- + +Additionally, anyone with push access to the master branch has access to cut +releases. diff --git a/docs/history.rst b/docs/history.rst deleted file mode 100644 index faf7adfe..00000000 --- a/docs/history.rst +++ /dev/null @@ -1,45 +0,0 @@ -:tocdepth: 2 - -.. _changes: - -History -******* - -.. include:: ../CHANGES (links).rst - -Credits -******* - -* The original design for the ``.egg`` format and the ``pkg_resources`` API was - co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first - version of ``pkg_resources``, and supplied the macOS operating system version - compatibility algorithm. - -* Ian Bicking implemented many early "creature comfort" features of - easy_install, including support for downloading via Sourceforge and - Subversion repositories. Ian's comments on the Web-SIG about WSGI - application deployment also inspired the concept of "entry points" in eggs, - and he has given talks at PyCon and elsewhere to inform and educate the - community about eggs and setuptools. - -* Jim Fulton contributed time and effort to build automated tests of various - aspects of ``easy_install``, and supplied the doctests for the command-line - ``.exe`` wrappers on Windows. - -* Phillip J. Eby is the seminal author of setuptools, and - first proposed the idea of an importable binary distribution format for - Python application plug-ins. - -* Significant parts of the implementation of setuptools were funded by the Open - Source Applications Foundation, to provide a plug-in infrastructure for the - Chandler PIM application. In addition, many OSAF staffers (such as Mike - "Code Bear" Taylor) contributed their time and stress as guinea pigs for the - use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!) - -* Tarek Ziadé is the principal author of the Distribute fork, which - re-invigorated the community on the project, encouraged renewed innovation, - and addressed many defects. - -* Jason R. Coombs performed the merge with Distribute, maintaining the - project for several years in coordination with the Python Packaging - Authority (PyPA). diff --git a/docs/index.rst b/docs/index.rst index 5a460526..33389a2f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,5 +10,5 @@ Documentation content: :maxdepth: 1 User guide - Development guide + Development guide Backward compatibility & deprecated practice diff --git a/docs/releases.rst b/docs/releases.rst deleted file mode 100644 index 35b415c2..00000000 --- a/docs/releases.rst +++ /dev/null @@ -1,37 +0,0 @@ -=============== -Release Process -=============== - -In order to allow for rapid, predictable releases, Setuptools uses a -mechanical technique for releases, enacted on tagged commits by -continuous integration. - -To finalize a release, run ``tox -e finalize``, review, then push -the changes. - -If tests pass, the release will be uploaded to PyPI. - -Release Frequency ------------------ - -Some have asked why Setuptools is released so frequently. Because Setuptools -uses a mechanical release process, it's very easy to make releases whenever the -code is stable (tests are passing). As a result, the philosophy is to release -early and often. - -While some find the frequent releases somewhat surprising, they only empower -the user. Although releases are made frequently, users can choose the frequency -at which they use those releases. If instead Setuptools contributions were only -released in batches, the user would be constrained to only use Setuptools when -those official releases were made. With frequent releases, the user can govern -exactly how often he wishes to update. - -Frequent releases also then obviate the need for dev or beta releases in most -cases. Because releases are made early and often, bugs are discovered and -corrected quickly, in many cases before other users have yet to encounter them. - -Release Managers ----------------- - -Additionally, anyone with push access to the master branch has access to cut -releases. -- cgit v1.2.1 From d507a9e4e5c13bb0d213ae5de4218e671e50882e Mon Sep 17 00:00:00 2001 From: alvy Date: Thu, 15 Oct 2020 17:03:54 -0400 Subject: revert the change of location of changelog file --- docs/development/history.rst | 45 -------------------------------------------- docs/development/index.rst | 1 - docs/history.rst | 45 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 46 deletions(-) delete mode 100644 docs/development/history.rst create mode 100644 docs/history.rst (limited to 'docs') diff --git a/docs/development/history.rst b/docs/development/history.rst deleted file mode 100644 index faf7adfe..00000000 --- a/docs/development/history.rst +++ /dev/null @@ -1,45 +0,0 @@ -:tocdepth: 2 - -.. _changes: - -History -******* - -.. include:: ../CHANGES (links).rst - -Credits -******* - -* The original design for the ``.egg`` format and the ``pkg_resources`` API was - co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first - version of ``pkg_resources``, and supplied the macOS operating system version - compatibility algorithm. - -* Ian Bicking implemented many early "creature comfort" features of - easy_install, including support for downloading via Sourceforge and - Subversion repositories. Ian's comments on the Web-SIG about WSGI - application deployment also inspired the concept of "entry points" in eggs, - and he has given talks at PyCon and elsewhere to inform and educate the - community about eggs and setuptools. - -* Jim Fulton contributed time and effort to build automated tests of various - aspects of ``easy_install``, and supplied the doctests for the command-line - ``.exe`` wrappers on Windows. - -* Phillip J. Eby is the seminal author of setuptools, and - first proposed the idea of an importable binary distribution format for - Python application plug-ins. - -* Significant parts of the implementation of setuptools were funded by the Open - Source Applications Foundation, to provide a plug-in infrastructure for the - Chandler PIM application. In addition, many OSAF staffers (such as Mike - "Code Bear" Taylor) contributed their time and stress as guinea pigs for the - use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!) - -* Tarek Ziadé is the principal author of the Distribute fork, which - re-invigorated the community on the project, encouraged renewed innovation, - and addressed many defects. - -* Jason R. Coombs performed the merge with Distribute, maintaining the - project for several years in coordination with the Python Packaging - Authority (PyPA). diff --git a/docs/development/index.rst b/docs/development/index.rst index d71d4dfc..28e653fe 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -33,4 +33,3 @@ setuptools changes. You have been warned. developer-guide formats releases - history diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 00000000..faf7adfe --- /dev/null +++ b/docs/history.rst @@ -0,0 +1,45 @@ +:tocdepth: 2 + +.. _changes: + +History +******* + +.. include:: ../CHANGES (links).rst + +Credits +******* + +* The original design for the ``.egg`` format and the ``pkg_resources`` API was + co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first + version of ``pkg_resources``, and supplied the macOS operating system version + compatibility algorithm. + +* Ian Bicking implemented many early "creature comfort" features of + easy_install, including support for downloading via Sourceforge and + Subversion repositories. Ian's comments on the Web-SIG about WSGI + application deployment also inspired the concept of "entry points" in eggs, + and he has given talks at PyCon and elsewhere to inform and educate the + community about eggs and setuptools. + +* Jim Fulton contributed time and effort to build automated tests of various + aspects of ``easy_install``, and supplied the doctests for the command-line + ``.exe`` wrappers on Windows. + +* Phillip J. Eby is the seminal author of setuptools, and + first proposed the idea of an importable binary distribution format for + Python application plug-ins. + +* Significant parts of the implementation of setuptools were funded by the Open + Source Applications Foundation, to provide a plug-in infrastructure for the + Chandler PIM application. In addition, many OSAF staffers (such as Mike + "Code Bear" Taylor) contributed their time and stress as guinea pigs for the + use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!) + +* Tarek Ziadé is the principal author of the Distribute fork, which + re-invigorated the community on the project, encouraged renewed innovation, + and addressed many defects. + +* Jason R. Coombs performed the merge with Distribute, maintaining the + project for several years in coordination with the Python Packaging + Authority (PyPA). -- cgit v1.2.1 From ab7fa51fef9b284d2a8723cc926e8c39db07208c Mon Sep 17 00:00:00 2001 From: alvy Date: Thu, 15 Oct 2020 17:08:57 -0400 Subject: fix dev-guide inclusion of fragment guide --- docs/development/developer-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/development/developer-guide.rst b/docs/development/developer-guide.rst index d2366931..13b07e7e 100644 --- a/docs/development/developer-guide.rst +++ b/docs/development/developer-guide.rst @@ -68,7 +68,7 @@ intended to solve. All PRs with code changes should include tests. All changes should include a changelog entry. -.. include:: ../changelog.d/README.rst +.. include:: ../../changelog.d/README.rst ------------------- Auto-Merge Requests -- cgit v1.2.1