Skip to content

Commit

Permalink
PEP 639: Move User Scenarios to an appendix and de-number
Browse files Browse the repository at this point in the history
  • Loading branch information
@CAM-Gerlach
CAM-Gerlach committed Feb 3, 2022
1 parent 988501a commit 85b2648
Showing 1 changed file with 150 additions and 150 deletions.
300 changes: 150 additions & 150 deletions pep-0639.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
=======================

Expand Down Expand Up @@ -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
-------------
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down

0 comments on commit 85b2648

Please sign in to comment.