PEP 639: Move User Scenarios to an appendix and de-number

Author: CAM-Gerlach

pep-0639.rst

@@ -43,13 +43,13 @@ The PEP also:
   tools converting legacy license metadata, adding license files and
   validating license expressions.
 
-- Discusses `user scenarios <User Scenarios_>`_,
-  describes a `reference implementation <Reference Implementation_>`_,
+- Describes a `reference implementation <Reference Implementation_>`_,
   analyzes numerous `potential alternatives <Rejected Ideas_>`_,
-  includes `detailed examples <Appendix 1. License Expression Examples_>`_ and
+  includes `detailed examples <Appendix: License Expression Examples_>`_,
+  explains `user scenarios <Appendix: User Scenarios_>`_ and
   surveys license documentation
-  `in Python packaging <Appendix 2. License Documentation in Python_>`_ and
-  `other ecosystems <Appendix 3. License Documentation in Other Projects_>`_.
+  `in Python packaging <Appendix: License Documentation in Python_>`_ and
+  `other ecosystems <Appendix: License Documentation in Other Projects_>`_.
 
 The changes in this PEP will update the
 `core metadata <#coremetadataspec>`_ to version 2.3, modify the
@@ -145,10 +145,10 @@ Rationale
 
 A survey of existing license metadata definitions in use in the Python
 ecosystem today is provided in
-`Appendix 2 <Appendix 2. License Documentation in Python_>`_ of this PEP,
+`an appendix <Appendix: License Documentation in Python_>`_ of this PEP,
 and license documentation in a variety of other packaging systems,
 Linux distros, languages ecosystems and applications is surveyed in
-`Appendix 3 <Appendix 3. License Documentation in Other Projects_>`_.
+`another appendix <Appendix: License Documentation in Other Projects_>`_.
 
 There are a few takeaways from the survey:
 
@@ -835,143 +835,6 @@ MUST NOT automatically infer a license expression, and SHOULD suggest that the
 package author construct one which expresses their intent.
 
 
-User Scenarios
-==============
-
-The following covers the range of common use cases from a user perspective,
-providing straightforward guidance for each. Do note that the following
-should **not** be considered legal advice, and readers should consult a
-licensed attorney if they are unsure about the specifics for their situation.
-
-
-I have a private package that won't be distributed
---------------------------------------------------
-
-If your package isn't shared publicly, i.e. outside your company,
-organization or household, it *usually* isn't strictly necessary to include
-a formal license, so you wouldn't necessarily have to do anything extra here.
-
-However, it is still a good idea to include ``LicenseRef-Proprietary``
-as a license expression in your package configuration, and/or a
-copyright statement and any legal notices in a ``LICENSE.txt`` file
-in the root of your project directory, which will be automatically
-included by packaging tools.
-
-
-I just want to share my own work without legal restrictions
------------------------------------------------------------
-
-While you aren't required to include a license, if you don't, no one has
-`any permission to download, use or improve your work <#dontchoosealicense_>`_,
-so that's probably the *opposite* of what you actually want.
-The `MIT license <#mitlicense_>`_ is a great choice instead, as it's simple,
-widely used and allows anyone to do whatever they want with your work
-(other than sue you, which you probably also don't want).
-
-To apply it, just paste `the text <#chooseamitlicense_>`_ into a file named
-``LICENSE.txt`` at the root of your repo, and add the year and your name to
-the copyright line. Then, just add ``license-expression = "MIT"`` under
-``[project]`` in your ``pyproject.toml`` if your packaging tool supports it,
-or in its config file/section (e.g. Setuptools ``license_expression = MIT``
-under ``[metadata]`` in ``setup.cfg``). You're done!
-
-
-I want to distribute my project under a specific license
---------------------------------------------------------
-
-To use a particular license, simply paste its text into a ``LICENSE.txt``
-file at the root of your repo, if you don't have it in a file starting with
-``LICENSE`` or ``COPYING`` already, and add
-``license-expression = "LICENSE-ID"`` under ``[project]`` in your
-``pyproject.toml`` if your packaging tool supports it, or else in its
-config file (e.g. for Setuptools, ``license_expression = LICENSE-ID``
-under ``[metadata]`` in ``setup.cfg``). You can find the ``LICENSE-ID``
-and copyable license text on sites like
-`ChooseALicense <#choosealicenselist_>`_ or `SPDX <#spdxlist_>`_.
-
-Many popular code hosts, project templates and packaging tools can add the
-license file for you, and may support the expression as well in the future.
-
-
-I maintain an existing package that's already licensed
-------------------------------------------------------
-
-If you already have license files and metadata in your project, you
-should only need to make a couple of tweaks to take advantage of the new
-functionality.
-
-In your project config file, enter your license expression under
-``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression``
-(Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your
-packaging tool, and make sure to remove any legacy ``license`` value or
-``License ::`` classifiers. Your existing ``license`` value may already
-be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc);
-otherwise, check the `SPDX license list <#spdxlist_>`_ for the identifier
-that matches the license used in your project.
-
-If your license files begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or
-``AUTHORS``, or you've already configured your packaging tool to add them
-(e.g. ``license_files`` in ``setup.cfg``), you should already be good to go.
-If not, make sure to list them under ``license-files.paths``
-or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
-(if your tool supports it), or else in your tool's configuration file
-(e.g. ``license_files`` in ``setup.cfg`` for Setuptools).
-
-See the `basic example`_ for a simple but complete real-world demo of how
-this works in practice, including some additional technical details.
-Packaging tools may support automatically converting legacy licensing
-metadata; check your tool's documentation for more information.
-
-
-My package includes other code under different licenses
--------------------------------------------------------
-
-If your project includes code from others covered by different licenses,
-such as vendored dependencies or files copied from other open source
-software, you can construct a license expression (or have a tool
-help you do so) to describe the licenses involved and the relationship
-between them.
-
-In short, ``License-1 AND License-2`` mean that *both* licenses apply
-to your project, or parts of it (for example, you included a file
-under another license), and ``License-1 OR License-2`` means that
-*either* of the licenses can be used, at the user's option (for example,
-you want to allow users a choice of multiple licenses). You can use
-parenthesis (``()``) for grouping to form expressions that cover even the most
-complex situations.
-
-In your project config file, enter your license expression under
-``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression``
-(Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your
-packaging tool, and make sure to remove any legacy ``license`` value or
-``License ::`` classifiers.
-
-Also, make sure you add the full license text of all the licenses as files
-somewhere in your project repository. If all of them are in the root directory
-and begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or ``AUTHORS``,
-they will be included automatically. Otherwise, you'll need to list the
-relative path or glob patterns to each of them under ``license-files.paths``
-or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
-(if your tool supports it), or else in your tool's configuration file
-(e.g. ``license_files`` in ``setup.cfg`` for Setuptools).
-
-As an example, if your project was licensed MIT but incorporated
-a vendored dependency (say, ``packaging``) that was licensed under
-either Apache 2.0 or the 2-clause BSD, your license expression would
-be ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. You might have a
-``LICENSE.txt`` in your repo root, and a ``LICENSE-APACHE.txt`` and
-``LICENSE-BSD.txt`` in the ``_vendor`` subdirectory, so to include
-all of them, you'd specify ``["LICENSE.txt", "_vendor/packaging/LICENSE*"]``
-as glob patterns, or
-``["LICENSE.txt", "_vendor/LICENSE-APACHE.txt", "_vendor/LICENSE-BSD.txt"]``
-as literal file paths.
-
-See a fully worked out `advanced example`_ for a comprehensive end-to-end
-application of this to a real-world complex project, with copious technical
-details, and consult a `tutorial <#spdxtutorial_>`_ for more help and examples
-using SPDX identifiers and expressions.
-
-
 Backwards Compatibility
 =======================
 
@@ -2066,8 +1929,8 @@ compatibility, while the same is not so if they are allowed now and later
 determined to be unnecessary or too problematic in practice.
 
 
-Appendix 1. License Expression Examples
-=======================================
+Appendix: License Expression Examples
+=====================================
 
 Basic example
 -------------
@@ -2258,8 +2121,145 @@ Some additional examples of valid ``License-Expression`` values::
     License-Expression: LicenseRef-Proprietary
 
 
-Appendix 2. License Documentation in Python
-===========================================
+Appendix: User Scenarios
+========================
+
+The following covers the range of common use cases from a user perspective,
+providing straightforward guidance for each. Do note that the following
+should **not** be considered legal advice, and readers should consult a
+licensed attorney if they are unsure about the specifics for their situation.
+
+
+I have a private package that won't be distributed
+--------------------------------------------------
+
+If your package isn't shared publicly, i.e. outside your company,
+organization or household, it *usually* isn't strictly necessary to include
+a formal license, so you wouldn't necessarily have to do anything extra here.
+
+However, it is still a good idea to include ``LicenseRef-Proprietary``
+as a license expression in your package configuration, and/or a
+copyright statement and any legal notices in a ``LICENSE.txt`` file
+in the root of your project directory, which will be automatically
+included by packaging tools.
+
+
+I just want to share my own work without legal restrictions
+-----------------------------------------------------------
+
+While you aren't required to include a license, if you don't, no one has
+`any permission to download, use or improve your work <#dontchoosealicense_>`_,
+so that's probably the *opposite* of what you actually want.
+The `MIT license <#mitlicense_>`_ is a great choice instead, as it's simple,
+widely used and allows anyone to do whatever they want with your work
+(other than sue you, which you probably also don't want).
+
+To apply it, just paste `the text <#chooseamitlicense_>`_ into a file named
+``LICENSE.txt`` at the root of your repo, and add the year and your name to
+the copyright line. Then, just add ``license-expression = "MIT"`` under
+``[project]`` in your ``pyproject.toml`` if your packaging tool supports it,
+or in its config file/section (e.g. Setuptools ``license_expression = MIT``
+under ``[metadata]`` in ``setup.cfg``). You're done!
+
+
+I want to distribute my project under a specific license
+--------------------------------------------------------
+
+To use a particular license, simply paste its text into a ``LICENSE.txt``
+file at the root of your repo, if you don't have it in a file starting with
+``LICENSE`` or ``COPYING`` already, and add
+``license-expression = "LICENSE-ID"`` under ``[project]`` in your
+``pyproject.toml`` if your packaging tool supports it, or else in its
+config file (e.g. for Setuptools, ``license_expression = LICENSE-ID``
+under ``[metadata]`` in ``setup.cfg``). You can find the ``LICENSE-ID``
+and copyable license text on sites like
+`ChooseALicense <#choosealicenselist_>`_ or `SPDX <#spdxlist_>`_.
+
+Many popular code hosts, project templates and packaging tools can add the
+license file for you, and may support the expression as well in the future.
+
+
+I maintain an existing package that's already licensed
+------------------------------------------------------
+
+If you already have license files and metadata in your project, you
+should only need to make a couple of tweaks to take advantage of the new
+functionality.
+
+In your project config file, enter your license expression under
+``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression``
+(Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your
+packaging tool, and make sure to remove any legacy ``license`` value or
+``License ::`` classifiers. Your existing ``license`` value may already
+be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc);
+otherwise, check the `SPDX license list <#spdxlist_>`_ for the identifier
+that matches the license used in your project.
+
+If your license files begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or
+``AUTHORS``, or you've already configured your packaging tool to add them
+(e.g. ``license_files`` in ``setup.cfg``), you should already be good to go.
+If not, make sure to list them under ``license-files.paths``
+or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
+(if your tool supports it), or else in your tool's configuration file
+(e.g. ``license_files`` in ``setup.cfg`` for Setuptools).
+
+See the `basic example`_ for a simple but complete real-world demo of how
+this works in practice, including some additional technical details.
+Packaging tools may support automatically converting legacy licensing
+metadata; check your tool's documentation for more information.
+
+
+My package includes other code under different licenses
+-------------------------------------------------------
+
+If your project includes code from others covered by different licenses,
+such as vendored dependencies or files copied from other open source
+software, you can construct a license expression (or have a tool
+help you do so) to describe the licenses involved and the relationship
+between them.
+
+In short, ``License-1 AND License-2`` mean that *both* licenses apply
+to your project, or parts of it (for example, you included a file
+under another license), and ``License-1 OR License-2`` means that
+*either* of the licenses can be used, at the user's option (for example,
+you want to allow users a choice of multiple licenses). You can use
+parenthesis (``()``) for grouping to form expressions that cover even the most
+complex situations.
+
+In your project config file, enter your license expression under
+``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression``
+(Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your
+packaging tool, and make sure to remove any legacy ``license`` value or
+``License ::`` classifiers.
+
+Also, make sure you add the full license text of all the licenses as files
+somewhere in your project repository. If all of them are in the root directory
+and begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or ``AUTHORS``,
+they will be included automatically. Otherwise, you'll need to list the
+relative path or glob patterns to each of them under ``license-files.paths``
+or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
+(if your tool supports it), or else in your tool's configuration file
+(e.g. ``license_files`` in ``setup.cfg`` for Setuptools).
+
+As an example, if your project was licensed MIT but incorporated
+a vendored dependency (say, ``packaging``) that was licensed under
+either Apache 2.0 or the 2-clause BSD, your license expression would
+be ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. You might have a
+``LICENSE.txt`` in your repo root, and a ``LICENSE-APACHE.txt`` and
+``LICENSE-BSD.txt`` in the ``_vendor`` subdirectory, so to include
+all of them, you'd specify ``["LICENSE.txt", "_vendor/packaging/LICENSE*"]``
+as glob patterns, or
+``["LICENSE.txt", "_vendor/LICENSE-APACHE.txt", "_vendor/LICENSE-BSD.txt"]``
+as literal file paths.
+
+See a fully worked out `advanced example`_ for a comprehensive end-to-end
+application of this to a real-world complex project, with copious technical
+details, and consult a `tutorial <#spdxtutorial_>`_ for more help and examples
+using SPDX identifiers and expressions.
+
+
+Appendix: License Documentation in Python
+=========================================
 
 There are multiple ways used or recommended to document Python project
 licenses today. The most common are listed below.
@@ -2384,8 +2384,8 @@ Other Python packaging tools
   ``pyproject.toml`` with SPDX license identifiers.
 
 
-Appendix 3. License Documentation in Other Projects
-===================================================
+Appendix: License Documentation in Other Projects
+=================================================
 
 Here is a survey of how things are done elsewhere.