Video summary
The August 25th meeting of the Application Runtime Interfaces Working Group began with a lighthearted acknowledgment of the summer break affecting many European attendees before diving into technical updates regarding documentation strategy. A significant development discussed was the recent merging of the generic experimental Open API repository directly into the main Cloud Controller codebase, placing it alongside V3 documentation. This integration allows developers to update both the V3 docs and the Open API specifications simultaneously through a single pull request, streamlining the process for API changes. Although the migration is still considered experimental due to missing details found in the V3 documentation, this step represents a clear move toward eventually deprecating the old V3 docs in favor of the Open API as the primary documentation source.
Despite this progress, challenges remain regarding the completeness of the migrated content, particularly concerning complex relationships between different API calls and operational procedures like pushing applications or setting up droplets. Participants noted that while many straightforward API calls have been successfully ported over using AI assistance, more intricate descriptions on how to compose these operations are still missing from the new documentation. To address these gaps, the group agreed that any feedback identifying missing information should be logged as issues to determine whether the content belongs in the Open API docs or the broader Cloud Foundry documentation. Additionally, it was suggested that publishing an experience report detailing issues encountered during the Stratus conversion could serve as a valuable reference document for future improvements.
The discussion also shifted toward architectural considerations for plugin separation within the CLI, specifically regarding serialization and transport layers. One participant sought guidance on how much of the CLI infrastructure should be extracted into a registry to allow for flexible combinations of serialization and transport methods, aiming to reduce tight coupling between plugins and the core CLI. While the general approach sounded reasonable to an outsider observer, it was advised that specific feedback on this architectural direction would come from the maintainers within the CLI working group area. The meeting concluded with administrative notes about pending pull requests related to usage events, directing interested parties to collaborate directly with Pete Levine, who is identified as the best contact for those matters.
In closing, the working group confirmed there were no outstanding action items from the previous session and approved the archiving of older specification repositories without requiring further approval from the Technical Oversight Committee. The attendees expressed satisfaction with the progress made on merging documentation systems and agreed to continue refining the Open API implementation before fully switching over. With the summer break acknowledged for everyone, the group adjourned with plans to reconvene next month, ensuring that any new topics or updates, such as those potentially from the RE working group, would be queued up for Stefan upon his return.
Read the full video transcript
Hello.
>> Morning.
>> All right. Well,
give another minute. If anyone else
shows up.
I suspect
everyone based in Europe is on vacation
currently, so
may not uh
>> Yeah, I think Stefan definitely is.
>> Can I put forward a RFC for an official
Cloud Foundry summer break?
>> Is that when we float on the Riviera?
>> Yeah, you can do as you please.
That's the that's the magic of summer
break.
All right.
Cool.
You can go ahead and start. I will share
the agenda.
Uh all right.
Welcome to the application runtime
interfaces working group meeting for
August 25th.
Uh checking action items from last time,
there were none. So, we achieved all the
action items. Good job, everyone.
Uh next one, working group changes.
So, I suspect we're about to talk about
this one potentially.
Uh
maybe we uh
fold that into next topic also.
Um so, should we just jump into talking
about
the open API stuff?
>> Sure.
Um yeah, so we had a separate repository
for generic experimental open API for
cloud controller for
uh
the API.
Um
and
we recently merged it in to
uh just the main cloud controller code
base. So, like alongside the V3 docs.
So, that way we can don't have to create
a separate PR for every API change. It's
still still experimental. We're still
not ready to like
fully switch over. It's missing a lot of
detail and um
uh uh that the V3 docs has.
Um so,
uh but now if you make any change to
cloud controller and you can
change both the V3 docs and the open API
with one PR.
Um
the get history is retained. It's a
little bit
not as uh straightforward as I
wish I was hoping it would be, but um
something to do with uh
subtrees and how they work in Git. I
don't fully understand, but
uh let me put the command
to see the Git history. So, like
you would need to run this command
to actually see
the log of commits in cloud controller.
Um
otherwise it just shows you shows you
the merge commit for bringing all in.
Yeah, this is one more step towards our
path of
deprecating the old V3 docs and
um
just switching over to open API as our
main doc.
There's a
uh
an issue I will link.
It's
right here.
Oh.
Well.
Um that issue is for like all the things
we need to do before we can switch over.
It's about it.
>> All right, and then there's Stefan's
related
uh open PR to
archive the uh
other the previous one
the spec.
>> Yeah, I'm not sure what we're waiting
for before we do this.
I don't think there's anything
>> Stefan to come back. I don't know. I
don't know if the
TOC would need to
I guess it's just marking it as
archived. Oh yeah, I don't know if the
TOC needs to approve this or not.
>> No, I think we could just merge this in
if
>> I approve it.
>> Thank you.
>> Uh yeah, maybe I can just merge this.
>> I have the power so why not?
>> Right.
>> Okay.
Um any other discussion on that topic?
>> The only thing I
found was
there's there's relationships between
the various different calls and in order
to do operations. I mean a lot of a lot
of the calls are pretty well, you know,
make the call, done with it, right?
But things like uh pushing an app or
setting up uh
droplets and stuff like that. Um I don't
see enough information that allows us to
define what those what those
relationships are between these calls.
And I'm wondering I ran into that when I
was working on the the strato stuff cuz
I had to needed to
add stuff so I had to go look at
the CLI code to figure out the
relationships and how they all work.
And I'm wondering if we need a section
like that
that I'm not sure that's an open API
style of thing versus because versus
just being a another document that says,
"Here's how you use things."
>> Right. So we So everything in this docs
is not been ported over yet. So like a
lot of this additional descriptions and
explanations here,
which I think the open API API docs does
have space for that. It just hasn't been
migrated over cuz we're trying to use AI
to to migrate all this over. And all the
actual
I think um API calls
most of that has been migrated over. But
so yeah, these sorts of descriptions and
like how to use things needs to be
double-checked that we have all that in
the Open API docs.
But, I think a lot of
how to compose these things may not even
be in these API docs. It may be in the
other Cloud Foundry general Cloud
Foundry docs.
Um yeah, so
uh yeah, I mean, if you have feedback
about like what you think is missing,
like please open that issue and we can
figure out if it fits here or if it fits
in the other API uh the other Cloud
Foundry docs.
>> You know, the
the analysis I got uh
my AI Claude said about
little little under 50% of it is pretty
straightforward. And then it starts
getting more complicated once you start
moving up into the
the other calls and how how to how the
how the relationships work.
>> Mhm.
>> And there's about 20
I think it's like, you know, 18 to 22%
of the other calls need other support
behind it
in order to be able to use them all
properly.
Um so um
maybe I'll I'll put something together
on that um and then put it out there.
Uh the
>> Even if you just publish like an
experience report of issues you ran into
while you were
uh converting over Stratus, that might
be a helpful document just for reference
purposes if for nothing else.
>> Okay. And then the other thing is I was
working I was getting ready to finalize
my um
the plugin documentation, you know, what
my proposal for V9.
And I wanted to
I think this is the group or at least
part of the group.
Um
I wanted to get a feeling for how much
do you want to separate out the plugins
from the CLI itself. As an example, we
can just say, "Hey, it it you know, the
serialization and the uh
uh
transport layer
is part of is part of the is part of the
CLI, therefore it's this is how you do
it.
I could even, you know, extract that
out, put it into a registry instead,
such that you can work with any
combination of serialization or
uh transport layer
uh and then and then just say, "Hey,
register this with this that." Um
I'm trying to get a feeling for how much
of this
separation you want from keeping the
plugins separated from the CLI because
you
you you locked yourself down last time
because you had to you built stuff for
it. And I'm trying to we're removing
that, right? For many for for most for
the most part.
So, now the tie-ins are
whatever you want to call a terminal
interface
the the serialization and the transport.
Right? And then everything else that be
beyond that is
can can be done directly through the uh
the Cappy interface, right? At that
point. So, there's very little that has
to be tied into it. So, in terms of how
help systems work, you know, that's that
type of stuff.
Um
that's the type of level that I like to
least define within the plugin so it
sees the the data is consistent when you
list it through the CLI interface.
Am I on the right track here or am I
going too far to the left or too far to
the right
um in terms of of terms of that?
Any
>> Yeah, I think for specific feedback, you
may want to reach out to the
uh
maintainers in the CLI working group
area.
>> Okay.
>> Um
I think
uh
Yeah, I think I mean, what what you're
saying in general sounds reasonable to
me as someone who's mostly an outsider
in that area.
>> Mhm.
>> Um
but I
But yeah, I think
I
Yeah, I think you'll get uh more
specific feedback if you reach out to
them and I can point you to some of the
people who are active in that area.
>> Okay, that'll be good.
Put me at the right people and then I
don't I can at least get directed.
I'm trying to get this all done before
uh
the meeting for next month, so
so there my there's something to talk
about, right? So.
>> All right, cool.
Uh any
other discussion about that?
Okay,
uh there's an item here, topics from the
working group area that I should mention
the RE working group update talk. I'm
guessing this is Stefan.
Unless one of you is secretly planning
to give a RE working group update talk.
Uh
so yeah, I guess if I
if anyone has any topics
uh
they want to cover at the summit,
put them in here for Stefan when he
comes back.
And I guess the obvious one is the uh
Once we talked about that
All right.
Any other topics?
>> I just want to ask about an
open PR I had
Pete Levine
kind of been one of the both commenting
on should I should I just maybe follow
up with him?
Um
to to like if if if
you know, he he gives approval and and
if I work with him to sort of go through
it, is that um
kind of adequate or do I need to like
kind of rope in any other
um
contributors maintainers?
>> Is this related to usage events?
>> Yes.
>> Yeah, I think Pete's is probably still
the best person to talk to about that.
>> Okay. Cool. Yeah, I I
work with him on the app usage stuff
sometimes as well, so we we've got a
good relationship.
>> All right.
Anything else on that?
>> Nope.
>> All right. Any other topics?
All right. Cool. Sounds good. Enjoy your
summer break everyone.
And I'll see you next month.
>> Thank you.
>> Thanks, folks.
>> Bye, everyone.
>> Bye.