Fixup the simple plugin setup docs.

Review Request #4241 — Created Sept. 16, 2016 and submitted

3877, 3878
patricklaw, peiyu, zundel
src/docs/ | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)
Rendered here:

CI went green here:
  • 0
  • 0
  • 0
  • 1
  • 1
Description From Last Updated
  1. Thanks, John. Mostly take-it-or-leave it comments below.

  2. src/docs/ (Diff revision 1)

    So, at one point I heard that plugin should be non-empty. Perhaps that is only for the internal pants plugins and has just been cargo culted everywhere.

    Ours say:


    It wouldn't surprise me to find out that it isn't required - I have never noticed an adverse effect when it wasn't included.

    1. A namespace package is required only if its required ;). This is only needed if you know or guess that the same python package (prefix) may be declared elsewhere so that the importer can merge packages successfully. If you own the namespace, there is no need. Granted, hadoop in this case is a pretty generic name and there very well could be some other pants code in-play that uses - say - a 3rdparty hadoop library that also uses, say hadoop.mapreduce and hadoop.namenode packages and then this would be a problematic example.

  3. src/docs/ (Diff revision 1)

    white space at EOL here

  4. src/docs/ (Diff revision 1)

    The details do not match the instructions here ("up to but not including the root directory") since there is no plugins/ file shown.

    1. It does match, since the root directory (aka source root, aka PYTHONPATH prefix) of the python package is plugins/, so up-to but not including means plugins/hadoop/ is the 1st package (ie: hadoop is a package and '' is not).
      That said, the wording is tripping up experienced python / pants people so that's not good. I'm open to concrete alternative wording.

  5. src/docs/ (Diff revision 1)

    I think I would remove the "When registering a backend in pants.ini" part of this paragraph. The pants.ini is discussed more in the next section.

  6. src/docs/ (Diff revision 1)

    It might be worth mentioning that pythonpath + the plugin's backend_packages entry should represent the path to the If you can think of a simple way to explain that.

    I used to get confusing registration errors until I finally understood that relationship.

    1. Yup - makes sense, a nice simple rule to apply to the finished product.  Added.
Review request changed

Status: Closed (submitted)

Change Summary:

Now on master:

git log -1 origin/master
commit 392c92c985cbc4c1eac8ef8da736c61b7ce4e89f
Author: John Sirois <>
Date:   Sun Sep 18 15:09:02 2016 -0600

    Fixup the simple plugin setup docs.
    Testing Done:
    Rendered here:
    CI went green here:
    Bugs closed: 3877, 3878
    Reviewed at
  1. Ship It!