add brief description of common extension points (#53)

* add brief description of common extension points

* Apply suggestions from code review

Co-Authored-By: Marya Belanger <[email protected]>

Author: dirk-thomas

developer/extension-point.rst

@@ -0,0 +1,85 @@
+Extension points
+================
+
+The following describes some of the extension points and how they are used.
+
+VerbExtensionPoint
+------------------
+
+This extension point is used by the ``colcon`` command.
+Each verb extension defines custom logic which can be invoked by calling ``colcon <verb>``.
+Each verb extension can add command line arguments to the verb specific subparser in ``argparse``.
+
+PackageDiscoveryExtensionPoint
+------------------------------
+
+This extension point is used by verb extensions.
+Each package discovery extension can add command line arguments which are grouped in the "Discovery arguments" section of the usage help.
+Each extension returns a set of package descriptors which identify a package with the tuple path, name, and type.
+While a package discovery extension only provides candidate paths it uses the package identification extension point to determine if a path contains a package.
+
+If explicit arguments are provided for any package discovery extensions only those extension are being used.
+Otherwise the package discovery extensions which provide a default value are used.
+
+PackageIdentificationExtensionPoint
+-----------------------------------
+
+This extension point is used by package discovery extensions.
+A package identification extension determines if a given path contains a package and returns the tuple path, name, and type.
+
+Package identification extensions are grouped by their priority.
+The extensions are invoked in order of their priority and the first extension successfully identifying a package stops further extensions from being considered.
+
+If multiple extensions have the same priority they are all invoked.
+If more than one extension within the priority group identifies the package in the given path the result must be identical or a warning is printed and the path is skipped.
+
+PackageAugmentationExtensionPoint
+---------------------------------
+
+This extension point is used by verb extensions after packages have been discovered and identified.
+A package augmentation extension can add arbitrary information to a package descriptor, like additional dependencies.
+
+PackageSelectionExtensionPoint
+------------------------------
+
+This extension point is used by verb extensions after packages have been discovered, identified, and augmented.
+Each package selection extension adds command line arguments which are grouped in the "Package selection arguments" section of the usage help.
+
+By default all packages are selected.
+Each extension can select / unselect matching package decorators based on the passed arguments.
+If arguments for multiple extensions are being passed the combined boolean flag is a logical ``AND`` combination.
+
+TaskExtensionPoint
+------------------
+
+This extension point is used by verb extensions after packages have been discovered, identified, and augmented.
+Each task extension implements the logic for the combination of a ``verb`` and a ``package type``, e.g. building a Python package.
+
+In order to be invoked a task extension needs parameters provided by a context object.
+A job object brings those two together.
+
+ExecutorExtensionPoint
+----------------------
+
+This extension point is used by some verb extensions to execute a set of jobs.
+The executor extension with the highest priority is used by default.
+
+ShellExtensionPoint
+-------------------
+
+This extension point is used by some task extensions to generate shells scripts to setup the environment or create environment hooks for each supported shell.
+Each extension implements the logic for a specific shell.
+For the primary shells each extension also provides the environment to run commands.
+
+EnvironmentExtensionPoint
+-------------------------
+
+This extension point is used by some task extensions as well as shell extensions to create environment hooks for each supported shell.
+Each extension creates environment hooks for a specific environment variable and uses the shell extensions to generate scripts for each supported shell.
+
+EventHandlerExtensionPoint
+--------------------------
+
+This extension point defines how events are handled.
+An event can be any kind of object, like a line of output, a job starting, progressing or ending, or a command executing.
+Every event is dispatched to all extensions in order of their priority.

index.rst

@@ -45,6 +45,7 @@ Information about development is also available:
    developer/bootstrap
    developer/environment
    developer/program-flow
+   developer/extension-point
    developer/contribution
    developer/changelog
 

spelling_wordlist.txt

@@ -18,9 +18,11 @@ prepend
 prepended
 pytest
 refactored
+subparser
 symlink
 symlinks
 templated
+unselect
 venv
 workflow
 yaml