Currently the docs are very geared toward those who setup, configure, and administer Pants. We've heard from many of you that part of your adoption process has been to produce simplified custom internal documentation for your end-users to refer to. We'd like to create some end-user oriented docs similar to that, to make that step easier for future adopters to accomplish. Something they can refer people to generically, and can easily adapt to incorporate internal details. (a) What is a good MVP for that? (b) Please do share your end-user docs, if you'd be comfortable, to help us identify what to cover. We want to learn from your deeper knowledge of what those end-users need.

We’ve heard from many of you that part of your adoption process has been to produce simplified custom internal documentation for your end-users to refer to. We’d like to create some end-user oriented docs similar to that, to make that step easier for future adopters to accomplish.

from a “don’t repeat yourself” perspective, i’d love to see it accomplished by tagging certain pages “administrator” vs “consumer”, rather than necessarily having separate content

along with a (possibly partial) index page for each, perhaps, to help navigate the doc space..

tagging certain pages “administrator” vs “consumer”, rather than necessarily having separate content

Depends on how long the example end user docs turn out to be. I'd like to get a look first at some examples. e.g. If it's typically just a 1-page cheatsheet, it may make more sense to maintain a separate resource. Potentially even via GH, where it's quick for admins to fork, remix, and add whitelabel.

FWIW our use case (and I imagine some amount of others) was to help re-map running <internal-tool> with running

./pants

@bitter-ability-32190 is yours essentially a two column cheatsheet of "Before" and "Now"?

(also, I haven't tried it, but) your document might say if you used https://github.com/Tinder/bazel-diff you can use

--changed

args

“before and after” type tables are insanely useful, yea. even if you aren’t familiar with both tools, they require actually enumerating relevant usecases. i don’t “know”

gdb

or

lldb

, but https://lldb.llvm.org/use/map.html is my go to when trying to learn how to do something.

I've explained using pants to a few people recently (including one for a mid-size python project handover), and when I point them to the docs - they get overwhelmed. But when I tell them that 95% of their time and effort in an existing repo will be typing like... 4 commands, I find everything becomes a bit more seamless. I essentially enumerate it (and lightly explain each step) as: •

git clone myrepo

•

./pants version

•

./pants test ::

•

./pants package :myawesomething

After they add new code, I show them: •

./pants fmt ::

•

./pants lint ::

(next comes deployment, but that's more complicated and repo-dependent) The only "challenges" I run into are explaining what the

::

means, and a few comments about global vs local vs auto-discovered dependencies when they create a new project in the monorepos. When they want to add a new project, they can look at the existing build files and almost copy/paste/rename. Anything more than that, I point at the docs. I personally don't even bother using the changed-since filters or anything, since VSCode handles auto-format and handles real-time lint/mypy. and then pre-commit hook handles the rest. I should also point out that I only use 1 BUILD file per subproject, rather than one per folder, so explaining that part is pretty easy.

Thanks @wide-midnight-78598!

I'm also thinking

pants

could use more tooling (like

tailor

, although could be one-off or standalone). Right now I need to find the easiest way to migrate to Pants for build+test, so I'd like to see a tree of my deps and work my way in.

In a slightly different direction, I've started populating a Conventions + Tips and Tricks page. I'm not sure it will be the most helpful, but it might inspire some ideas of things to add for incremental adoption or troubleshooting sections.

THANK YOU @high-yak-85899!

@high-yak-85899 +1 for BUILD.pants, I also use that everywhere. The word BUILD gets so much usage in so many scenarios for folders and files and build tooling in my repos that it becomes hard to search or grep for, or I'm always worried some of my build process will interfere with it (has already happened, in fact)

Especially since it's perfectly fine to use Pants and e.g. Bazel side-by-side in the same repo.

Technically, speaking yes. But yuck 😉

Depends on the composition of the codebase. If it's a mix of Python, where Pants is the clearly better choice, and a language where Bazel offers stronger support, then it can make sense to take advantage of where each is respectively strongest. Though yeah, having to remembering two sets of commands, mentally shift between different target models, etc would not be my personal happy place.

Our team would gladly drop bazel if Pants supported C++ and custom toolchains

I hope you put both of those on the radar of the community roadmap survey!