flat-zoo-31952
08/17/2022, 5:40 PM./pants help goals
etc), which probably muddies the waters about the distinction between experimental and non-experimental features
• Moving from an "experimental_" name to the eventual stable name is a breaking API change itself. Granted, those using this name would be opting-in to potential changes, but still, it could be annoying, especially if you need to revert back to a previous version where autofixers might not help you
• If we're just going to prefix things to mark them as unstable, "experimental" is a long choice. Other words ("alpha_", "beta_", "labs_", "contrib_" or even just "_") might be better if we stick with just a prefix conceptbitter-ability-32190
08/17/2022, 5:49 PMbeta_
to experimental
🙂flat-zoo-31952
08/17/2022, 5:50 PMpants.backends.explorer
as
./pants pants.backends.explorer:Explorer ...
with the idea that once it becomes stable, you could reserve a proper alias for it, but that path reference would keep workingbitter-ability-32190
08/17/2022, 5:56 PMflat-zoo-31952
08/17/2022, 5:57 PMwitty-crayon-22786
08/17/2022, 6:07 PMwhich probably muddies the waters about the distinction between experimental and non-experimental featuresthey do, but always as prefixed with `experimental-`… which makes it very, very clear what they are. so yea, it requires a deprecation cycle to rename the goal, but that can easily be a very, very long deprecation. note also though that goals won’t show up if they don’t have any implementations. so
experimental-bsp
and experimental-deploy
(for example) won’t show up unless the java
/ scala
and helm
backends are enabled (respectively). i.e. you already need to have opted into an experimental thingalpha
or labs
probably, although the latter might be novel in a not-great waybitter-ability-32190
08/17/2022, 6:08 PMlabs
in the wild, so newbie me would've had to go googling WTF labs-bsp
is)happy-kitchen-89482
08/17/2022, 6:52 PMalpha
or labs
or whatever in the registration string is fine, but not in end-user facing things like goal names or target names?wide-midnight-78598
08/17/2022, 6:59 PMexperimental
FWIW. I think if it's something that's actually in an experimental state, it should be unconditionally clear that is the state. I've quite liked Kotlin's handling of this (https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.experimental/) - because you know what you're getting into when using those namespaces.
alpha/beta/gamma/omega or whatever implies that in a release or two, those should have gone away.happy-kitchen-89482
08/17/2022, 7:00 PMexperimental_shell_command
wide-midnight-78598
08/17/2022, 7:01 PMbeta_target
I probably wouldn't hesitate to use it, assuming it's just a polishing away from being perma.witty-crayon-22786
08/17/2022, 7:01 PMexperimental_shell_command
was exactly that we don’t know what the final name should be (…not to mention the rest of the API)proud-dentist-22844
08/17/2022, 7:08 PMcontrib
- that is such a vague and uninformative thing. To me it means "this thing is contributed by someone who is not a core dev, so their stuff is second or third class and probably not very good, so YMMV. we are only distributing it, and not supporting it"labs
. I can see using labs
in gmail, element, and other web interfaces where an end user of the GUI interface can toggle some switches. labs
does not belong in a primarily cli tool, because many companies are named "something labs", so everything comes from a lab somewhere, and seeing labs
in a namespace is pretty meaningless.flat-zoo-31952
08/17/2022, 7:15 PMnote also though that goals won’t show up if they don’t have any implementations. soI'm gettingandexperimental-bsp
(for example) won’t show up unless theexperimental-deploy
/java
andscala
backends are enabled (respectively). i.e. you already need to have opted into an experimental thinghelm
experimental-explorer
and experimental-bsp
in ./pants help goals
despite having none of those backends enabledwitty-crayon-22786
08/17/2022, 7:17 PMhappy-kitchen-89482
08/17/2022, 7:22 PM(having said that: if it had been hidden behind an experimental backend, maybe it would not itself have needed to be marked experimental… but it wouldn’t have dodged the need to rename it when stabilizing)Exactly, I think the backend should be marked experimental, because changing that name affects one config file line. But the target name should not have been, because it affects potentially many BUILD files.
shell_command
, but we definitely need to rename experimental_shell_command
, so naming it that didn’t gain us anythingbusy-vase-39202
08/17/2022, 7:25 PMwide-midnight-78598
08/17/2022, 7:28 PMexperimental
more as being "volatile APIs" - so odds are if it's a language, sdk, API, or something that even made it to getting published or docs - the concept is planned to exist, but with zero promises on what the API will look like.
If I was using a beta
(or sometimes even an alpha
) that should come with a reasonable-ish timeframe, and some reasonable API stabilitywitty-crayon-22786
08/17/2022, 7:28 PMbusy-vase-39202
08/17/2022, 7:35 PMwitty-crayon-22786
08/17/2022, 7:36 PMunstable
, but then requiring a tracking issue (á la rust, as mentioned in the meeting) which explains “how unstable” it is.proud-dentist-22844
08/17/2022, 7:38 PMunstable
hundreds-father-404
08/17/2022, 7:40 PMunstable
more than experimental
! (Although we should not rename existing things to use that)wide-midnight-78598
08/17/2022, 7:40 PMfuture
- but I don't think that describes stabilitybusy-vase-39202
08/17/2022, 7:40 PMproud-dentist-22844
08/17/2022, 7:42 PM__future__
in python denotes an API in a future release that is available as an opt-in in the current release. So no wiggle room on how the API will look. So with my python glasses on, I'd rather not use future
.wide-midnight-78598
08/17/2022, 7:44 PMAPI in a future release that is available as an opt-in in the current releaseFair point.
proud-dentist-22844
08/17/2022, 7:44 PMbitter-ability-32190
08/17/2022, 7:45 PMwide-midnight-78598
08/17/2022, 7:45 PMbusy-vase-39202
08/17/2022, 7:46 PMflat-zoo-31952
08/17/2022, 7:46 PMwide-midnight-78598
08/17/2022, 7:50 PMmagicword
to stable, and end user would never know.
In the non-best cases, prefixing targets with magicword
guarantees that it'll affect everyone, with ... some ... benefit?busy-vase-39202
08/17/2022, 7:51 PMwide-midnight-78598
08/17/2022, 7:52 PMkotlin.experimental
or switching over to androidx
- if fix
takes care of the boilerplate within a reasonable degree, I typically don't care whether namespaces change.one company that there were concerns raised about how much Pants appeared to be [experimental|unstable|alpha|beta|unfinished]I find this super strange, assuming each language is treated like a plugin - why would additional plugins make people view a tool as unstable? That's like me calling VSCode unstable, because they have an experimental XYZ extension support? Very odd...
busy-vase-39202
08/17/2022, 7:56 PMwide-midnight-78598
08/17/2022, 7:56 PMbitter-ability-32190
08/17/2022, 7:57 PMexperimental
)busy-vase-39202
08/17/2022, 7:57 PMflat-zoo-31952
08/17/2022, 8:12 PMbitter-ability-32190
08/17/2022, 8:47 PMmuslin
? https://en.wikipedia.org/wiki/Muslin#Dressmaking_and_sewing
These test-models are sometimes referred to as "muslins" in the United StatesThere's no association so: 1. People reading it have no assumptions 2. We have to document it Not saying this is my vote to replace
experimental
, just saying if we have to choose one this one is unique and clever 😉wide-midnight-78598
08/17/2022, 8:47 PMjust saying if we have to choose one this one is unique and cleverOr, the EXACT OPPOSITE... ... ...
next
proud-dentist-22844
08/17/2022, 8:49 PMbitter-ability-32190
08/17/2022, 8:49 PMnext
implies to me it'll be in the next releasewide-midnight-78598
08/17/2022, 8:49 PMbitter-ability-32190
08/17/2022, 8:50 PMnext
wide-midnight-78598
08/17/2022, 8:50 PMmagicword
it tries to be something already used in existing ecosystem of languages and tools, and is not too clever to hinder/confuse non-native-English speakers by default
The amount of French punny code I've had to deal with in my life... sighdry-analyst-73584
08/17/2022, 11:21 PMbusy-vase-39202
08/17/2022, 11:26 PMdry-analyst-73584
08/17/2022, 11:26 PMbusy-vase-39202
08/17/2022, 11:31 PMmuslin
making a good blog post and short definition box for the docs. It's not a common term among programmers, but it's not a joke. It's an apt sewing allusion, like tailor
.bitter-ability-32190
08/17/2022, 11:55 PMdry-analyst-73584
08/17/2022, 11:58 PMflat-zoo-31952
08/18/2022, 1:33 PMhappy-kitchen-89482
08/18/2022, 3:24 PMflat-zoo-31952
08/18/2022, 4:10 PMhundreds-father-404
08/18/2022, 4:14 PMunstable
or experimental
. Although I won't block
I agree with 3 where possible. Sometimes it is not, like experimental options for a stable backend (Python)
For 1, I encourage limiting ourselves to one level for things that users have to type in config files, so they don't have to migrate from .alpha
to .beta
. It's worked nicely to call the code experimental
, then in our docs clarify whether it means Alpha, Beta, etcbitter-ability-32190
08/18/2022, 4:15 PMpython
will have --bikeshed-python
to "namespace" the experimental options.
Public goals can be augmented through a similar subsystemThey require learning custom jargon.I mean,
target
, target generator
, subsystem
, goal
, source roots
, macros
were all new-ish to me when I joined. BUILD
and backends
could be seen as "new" to someone not familiar with similar tech.
These (except "subsystem" which is not defined/documented anywhere) are all documented/defined here https://www.pantsbuild.org/v2.13/docs/conceptsproud-dentist-22844
08/18/2022, 4:31 PMexperimental
-> fudless
🧌flat-zoo-31952
08/18/2022, 5:08 PMtarget
probably works well for anyone familiar with make
, even if Pants' use of it is a bit different. While there's some danger that people may not get, say, all source files can be targets in Pants' model of the world, it's close enough and can be explained.
Worse is something like BUILD
, which a large, large number of people seem to think is intrinsically related to compilation, or Jenkins, or something like that. To me "build" can mean practically any set of actions I take on source code, but that's arguably a very jargon-y definition. Not everyone has read Build Systems à la Carte. I've learned to be careful about this particular word in CI talks because it can lead to so much confusion for people who wonder what I'm doing to compile Python code all the time. It's possible we could have called this process "sewing" and the files SEAM
files, and while it would be silly, at least using the novel names with little context would signal to listeners that it is a novel concept and you should suspend your judgement for a second to figure out what we mean.
My point is that intuition is a neat goal, but it's not an unqualified win all the time, because you take the good with the bad. But I think the razor may be just this: when you want someone to suspend judgement, use novel terms. When you want them to bring their experiences to bear, use familiar ones. I think we need to judicious in how many novel terms we introduce, for fear of learning fatigue, but it's not wrong to introduce some things like that sometimes.hundreds-father-404
08/18/2022, 5:43 PMbusy-vase-39202
08/18/2022, 5:48 PMnovelTerm
don't have the baggage, so while I don't feel strongly about which novel term to choose I am inclined to prefer some kind of novel term since it eliminates the unintended validation of others' FUD.wide-midnight-78598
08/18/2022, 7:04 PMIt's possible we could have called this process "sewing" and the filesIn thinking about it, it's a shame they werent calledfilesSEAM
PANTSFILES
or PANTSBUILD
files - seems to be de rigueur for each tool to have its own named configurationsbitter-ability-32190
08/18/2022, 7:07 PMWORKSPACE
and BUILD
would like a word 🙄flat-zoo-31952
08/18/2022, 7:10 PM.BUILD
internally for the time beingbitter-ability-32190
08/18/2022, 7:10 PMBUILD.pants
, but generally speaking...flat-zoo-31952
08/18/2022, 7:11 PMBUILD
is fine, it was just an example of the tradeoff that happens when naming things in a way that appeals to intuition: some people may have the wrong intuitionbitter-ability-32190
08/18/2022, 7:12 PMwide-midnight-78598
08/18/2022, 7:22 PMBUILD.pants
person too - ambiguity significantly reducedbitter-ability-32190
08/18/2022, 8:22 PMbusy-vase-39202
08/18/2022, 8:23 PMexperimental
.flat-zoo-31952
08/18/2022, 8:35 PMwide-midnight-78598
08/19/2022, 7:48 PMbusy-vase-39202
08/19/2022, 8:05 PM