A lot of people create a proof of concept branch or repo to help sell their team on how the group would benefit from choosing to adopt Pants. For those who've done that, could you elaborate on what you did (or are doing?). It would help us to understand what early steps are common on the path toward adoption.

I've generally found three different aims, which guide different experiments/demos: 1. How does the tool work? 2. How does the tool scale? 3. How well -matched is the tool to our codebase(s) For 1, I want a small hello world repo with one or two of each thing I care about (libraries, binaries, tests, third party dependencies, languages, etc). And try out all of the workflows you care about. For 2 and 3, trying to retrofit the tool to an existing codebase (generally being willing to make whatever changes are necessary, including breaking the old system if there is one). Being able to side-by-side do the same operations in two clones at the same commit. Showing a demo of some killer reason to switch ("look how fast running the first test is" or "look how fast re-running a test after an incremental change is" or "look how everything works with no boilerplate" or whatever). Then once I have a single compelling value proposition, hand the branch to other people and let them play around themselves. Super important to be upfront about what is unlikely to work ("I haven't ported any of the thrift, I'm re-using pregenerated artifacts" or "the IDE doesn't work at all"), and which things are easily fixable vs hard vs unknown ("I haven't bothered to do thrift but it would be trivial" / "this tool would be hard to use with thrift" / "no idea whether thrift would be easy or hard")

So I am in the middle of this process for my employer and decided to go with a green-field repository. It contains minimal library and tool code that is just complex enough to represent our use cases. That way, I can focus on the tooling and the repository layout without my colleagues getting bogged down in complicate code. Given the importance of automated CI, I made sure that the proof-of-concept does have CI configured. As it turned out, making Pants test all impacted packages in the repo as well as their dependees is a single-line job — which is fantastic and really impressive. For that to work, however, the CI mustn't do a shallow clone. GitLab for one defaults to just that and figuring out which setting to tweak was a bit painful. For the record, you need to remove the number under "Git shallow clone" in the "General pipelines" section of the "CI / CD" settings. Alas, I'm currently fighting with documentation generation, which appears to be a far less awesome story. There doesn't seem to be any Pants support for Sphinx yet. Correct? And how have others dealt with the fact that Sphinx loads the packages it documents? That would seem to be a job for a PEX but that also requires setting up Sphinx correctly.

Thanks for that helpful feedback about GitLab config. That would be a really useful addition to the docs too. Would you be comfortable adding it, using the "Suggest Changes" button?

Hi Carina, sure, I'm happy to do that. The documentation is in the main repo on GitHub? Or is that separate docs repo?

It's at pantsbuild.org/docs

Ah, nifty and supermarket syndrome at its best: I've been consulting the docs a lot of late and never noticed the little suggestion button. I'm guessing the detail about GitLab best fits on the "advanced target selection" page. Ok?

Sure, apply your best judgement. The suggestion will be reviewed by maintainers and if necessary can be moved if they think it fits better in a different place.

Probably best on https://www.pantsbuild.org/docs/using-pants-in-ci

"CI Vendor-Specific Tips"?

Sounds good. I already made the change on advanced target selection and will add it to the CI page too. Personally, I like repetition on stuff like that. It makes sure people see it.

Good point. When it's brief, I'd rather stumble on it twice than not at all.

That sounds familiar. Not a fan either. 🙂

Thanks for saving the next bunch of people from some headaches!

I don't often set out to do "green field" or anything. I have projects I work on, and I have particular issues I look to solve. I do a lot of research up front and then dive in to implement the solution I chose. I have a few general requirements for software I'm using to solve whatever problem is at hand. I will only champion projects that are open source, so that is one of the first things I check. I look at the underlying technology to see if it is something I consider dangerous/painful (I refuse to use Java-based programs unless there is no other choice, and I avoid Ruby because I've had tons of problems with it in the past). I give preference to projects that use a language I know or want to learn because I like to fix bugs as I find them (python, golang, shell, rust). For the StackStorm project, the problems I've been working on solving with pants are (1) flaky ci, (2) dependency management hell, and (3) developer experience. We have waisted so much time on CI infra that is spread across multiple repos written in a variety of different languages (including at least makefile, yaml, python, ruby, shell, rpm spec, deb files, Dockerfile) and multiple CI services (luckily only circle and GHA now that Travis forced us to stop using them). The mess of makefiles, random scripts, and Ruby are mostly incomprehensible. Figuring out how to set up a local developer environment is a nightmare. Something else seems broken nearly every time I try to say up a local sev environment. Now that I've spent many full days (weeks?) Studying all of this mess, I have a better idea of where to look to figure out how to fix the infra so I can actually work on the pieces I wanted to work on. Frequently broken CI has wasted a lot of precious time. I've been so annoyed with it all that I've taken to leaving all testing to CI pushing countless "debug" commits, so much that other Maintainers have complained about all the email generated when I'm debugging something. I read a lot of the pants docs as part of my intense research to understand how pants works and see if it has the potential to resolve my target issues. So, I created a StackStorm fork that I periodically update with upstream. In that fork, my goal is to introduce pants with minimal changes to the existing code and the mess of makefiles+etc so that pants can run side by side with existing CI infra until the fork is ready to merge with upstream. Only after pants is merged will I work on ripping out the makefile hell. I've been slowly enabling one tool at a time in pants. I had to run tailor to populate the many BUILD files. And then I've had to edit the BUILD files over and over to try and capture all of the dependency information that pants can't infer. With each tool, I run pants with the one tool over and over until I've captured all of the dependency info needed to run that tool successfully, then I add another tool and do it again. With the

skip_<tool>

parameters, that process should be even easier because I could enable a tool and run it on just one directory at a time. Once I was far enough along locally to see some positive results, I started working on getting pants running in GHA. That's kind of where I'm at. I need to get constraints/lockfile that work both locally and in GHA. Much of the value I see in pants is in replacing the makefile madness with a single point of entry. Though I'm gradually adding pants tooling, I will present it to the StackStorm community in more of a big bang switch over. I don't want to add yet another tool (pants) until we can rip out makefiles, thus clearly simplifying the infra.