https://pantsbuild.org/ logo
#general
Title
# general
b

busy-vase-39202

01/31/2022, 7:57 PM
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.
5
w

witty-crayon-22786

01/31/2022, 7:58 PM
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
👍 1
c

curved-television-6568

01/31/2022, 8:08 PM
along with a (possibly partial) index page for each, perhaps, to help navigate the doc space..
1
b

busy-vase-39202

01/31/2022, 8:22 PM
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.
b

bitter-ability-32190

01/31/2022, 8:24 PM
FWIW our use case (and I imagine some amount of others) was to help re-map running <internal-tool> with running
./pants
+ Bazel re-mapping, which I suppose y'all could document 🙂 (For build + test). E.g. Document how to go from a Bazel "address" (or whatever they are called) into a Pants one
b

busy-vase-39202

01/31/2022, 8:25 PM
@bitter-ability-32190 is yours essentially a two column cheatsheet of "Before" and "Now"?
1
E.g. Document how to go from a Bazel "address" (or whatever they are called) into a Pants one 
That sounds like a good blog post as well.
b

bitter-ability-32190

01/31/2022, 8:26 PM
(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
w

witty-crayon-22786

01/31/2022, 9:25 PM
“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.
w

wide-midnight-78598

01/31/2022, 9:27 PM
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.
👍 1
1
b

busy-vase-39202

02/01/2022, 1:45 AM
Thanks @wide-midnight-78598!
b

bitter-ability-32190

02/01/2022, 2:51 PM
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.
h

high-yak-85899

02/02/2022, 1:13 AM
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.
🙌 2
3
❤️ 2
b

busy-vase-39202

02/02/2022, 1:31 AM
THANK YOU @high-yak-85899!
1
👆 1
w

wide-midnight-78598

02/02/2022, 3:49 AM
@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)
1
🧠 2
b

busy-vase-39202

02/02/2022, 5:14 PM
Especially since it's perfectly fine to use Pants and e.g. Bazel side-by-side in the same repo.
b

bitter-ability-32190

02/02/2022, 5:17 PM
Technically, speaking yes. But yuck 😉
b

busy-vase-39202

02/02/2022, 5:23 PM
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.
1
h

high-yak-85899

02/02/2022, 5:26 PM
Our team would gladly drop bazel if Pants supported C++ and custom toolchains
b

busy-vase-39202

02/02/2022, 5:29 PM
I hope you put both of those on the radar of the community roadmap survey!
2
5 Views