add sig-api charter

[alaypatel07]

What this PR does / why we need it:

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #

Special notes for your reviewer:

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

• Design: A design document was considered and is present (link) or not required
• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and Keep it simple
• Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
• Upgrade: Impact of this change on upgrade flows was considered and addressed if required
• Testing: New code requires new unit tests. New features and bug fixes require at least on e2e test
• Documentation: A user-guide update was considered and is present (link) or not required. You want a user-guide update if it's a user facing feature / API change.
• Community: Announcement to kubevirt-dev was considered

Release note:

[kubevirt-bot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[kubevirt-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign rmohr for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[alaypatel07]

cc @EdDev @fabiand

[iholder101]

/cc

[vladikr]

/hold

[vladikr]

@alaypatel07 thank you very much for posting this PR.
API is a critical part of the KubeVirt project.
An approver in this area would be someone who made a significant contribution (reviews and code) in most project areas. So far we had this document as a guiding principle https://github.com/kubevirt/community/blob/main/membership_policy.md#approver

[alaypatel07]

@vladikr Thanks for the link, however I am not following the context, can you be more specific as to what you are recommending here?

This PR does not deal with approvers/reviewers list yet. It is mostly consolidating on the work that is done is sig-api calls since September 19, 2023. https://docs.google.com/document/d/1LCLt5k9x1yISZE_0SxGb5hcU3Q0pzDqRfIMEffgqlnk/edit?usp=sharing

[vladikr]

While sig-compute will focus on the node level aspects, Sig-api will need to be responsible for the kubevirt control plane components and deployment such as virt-api, virt-conrtoller, and virt-operator.

[EdDev]

As I see it, the scope is not about a specific logic or features content, but on how to expose them for usage through the API in a safe and stable manner.

Could you be specific and point out which of the items listed here requires rephrasing, removing or which items are missing?

At the moment, I see that all of the items are described in a supportive manner. I mean, trying to provide means to write safe and stable APIs.

[fabiand]

Yes, let me second @EdDev .

IIUIC - and how I would support it - SIG API is exclusively about guarding our public APIs (everything in CRDs)., and not about their implementation.

It is to ensure that we have

• good API patterns
• avoid repeating API mistakes
• achieve more consistency between APIs
• ensure proper life-cycling of APIs (incl FGs).

Thus I am in favor of scoping SIG API in that way.

@vladikr so far I'm seeing the components that you had mentioned still to be in the domain of sig compute.

[vladikr]

@fabiand I don't think that sig-compute knows about this responsibility.
If you look at Sig API Machinery, the focus there is on everything that affects the control plane.

I see very little value and a risk for a bottleneck in a sig that is only responsible for writing APIs without the knowledge and responsibility of how these APIs affect the rest of the components.

[EdDev]

@vladikr , this proposal is not related to api-machinery, it is related to the API governance subproject of sig-architecture.
It is actually a portion of that subproject, as it only focused on the API part.

I see very little value and a risk for a bottleneck in a sig that is only responsible for writing APIs without the knowledge and responsibility of how these APIs affect the rest of the components.

The SIG is not responsable to write APIs, it is responsible to provide guidance and protect the project API, keeping it safe in terms of comparability, dependability and consistency.

IMO the project reached a size that makes it hard for all maintainers/approvers to consider all API concerns and avoid conflict of interest with other concerns (functionality, code quality, delivery due time).

I would expect the SIG-API to evaluate an API change and seek/ask for several alternatives before it is being accepted.
This may be considered a bottleneck, although this charter is not hinting anything about enforcing at this stage. I think it makes sense to be very careful when introducing API changes at this stage, it should be much harder than before, with more discussions taking place.
I think we are not yet in a good position today, although awareness has increased.

[fabiand]

To me +1 about the scope

This sig is not implementing APIs, it's rather focused on establishing standards around it - as described below.

Implementing, and maintaining APIs is still up to the other SIG (whoever is providing it), and the machinery is currently owned by sig compute (IIUIC) - but this is separate from this proposed sig.

Btw - one takeaway could be @EdDev @alaypatel07 to call this sig sig-api-governance.

[EdDev]

@alaypatel07 thank you very much for posting this PR. API is a critical part of the KubeVirt project. An approver in this area would be someone who made a significant contribution (reviews and code) in most project areas. So far we had this document as a guiding principle https://github.com/kubevirt/community/blob/main/membership_policy.md#approver

@vladikr Thanks for the link, however I am not following the context, can you be more specific as to what you are recommending here?

At the moment, the sig-api have no approvers in any of the Kubevirt organization repos.
The actual work done so far and the charter proposed here is de-facto in an advising work mode. If something needs to be rephrased to clarify that, please propose a change. (I tried to read it several times now and I see nothing that hints about acting as veto on any topic)

So I am also looking for clarification on how this is related to approvers.
If acting chairs are also expected to be approvers, please clarify. The current names only reflect the most active members that joined the weekly meeting and took actions in the list of scopes mentioned.

[EdDev]

As I see it, the scope is not about a specific logic or features content, but on how to expose them for usage through the API in a safe and stable manner.

Could you be specific and point out which of the items listed here requires rephrasing, removing or which items are missing?

At the moment, I see that all of the items are described in a supportive manner. I mean, trying to provide means to write safe and stable APIs.

[vladikr]

@vladikr Thanks for the link, however I am not following the context, can you be more specific as to what you are recommending here?

Thanks @alaypatel07 .
While I didn't find an explicit definition of the sig-chair - I would expect sig-chairs to be part of the approvers of this sig. (defined in the https://github.com/kubevirt/kubevirt/blob/main/OWNERS_ALIASES)

Here are some links to review:
https://github.com/kubevirt/community/blob/2bee0a7984d640fee486d721207d4518a5bda25b/sig-governance.md
https://github.com/kubevirt/community/blob/2bee0a7984d640fee486d721207d4518a5bda25b/sig-charter-guide.md

This PR does not deal with approvers/reviewers list yet. It is mostly consolidating on the work that is done is sig-api calls since September 19, 2023. https://docs.google.com/document/d/1LCLt5k9x1yISZE_0SxGb5hcU3Q0pzDqRfIMEffgqlnk/edit?usp=sharing

Indeed. Following the proposal sigs that were previously defined as interest groups. These are now evolving into a formal entity that will take ownership of certain components of the project to ensure its quality.
Therefore the scope of the sig will need to change as well.

[alaypatel07]

@vladikr I found this section which does not require a sig-chair to be an approver, on the contrary a member can serve as a lead:

Leads MUST be at least a "member" on our contributor ladder to be eligible to hold a leadership role within a SIG.

https://github.com/kubevirt/community/blob/2bee0a7984d640fee486d721207d4518a5bda25b/sig-governance.md#requirements

[iholder101]

@vladikr I found this section which does not require a sig-chair to be an approver, on the contrary a member can serve as a lead:

Leads MUST be at least a "member" on our contributor ladder to be eligible to hold a leadership role within a SIG.

2bee0a7/sig-governance.md#requirements

This list of requirements seems very vague, and the only real requirement there is to be a community member. I think we can agree that this requirement is not enough on its own.

There's also this point, which is also vague:

SIGs MAY prefer various levels of domain knowledge depending on the role. This should be documented.

I think that the sig chair role is not well-defined, both in terms of the actual role and the authority, responsibility and commitment that comes along with it.

I think we should discuss the following questions regarding sig chairs:

• What are sig chair's responsibilities? Current docs mention SHOULD define how priorities and commitments are managed. Does it mean that a chair can decide which features have more/less priority? Does it mean he decides who's assigned to different tasks? Or are we solely talking about managing the sig's meeting and dealing with bureaucracy?
• What is sig chair's authority, if any? Can chairs block a feature proposal? a PR?
• What are the requirements to becoming a chair? Even if we're talking about a role that's completely bureaucratic in nature I'd still expect from chairs to be familiar with the project, have some kind of technical knowledge and to be involved in the organization for a while. The bar should be dramatically higher if a chair's role is technical rather than bureaucratic (e.g. if he's setting priorities, etc, as described in the above bullet) or if the chair has any technical authority.

[EdDev]

@vladikr I found this section which does not require a sig-chair to be an approver, on the contrary a member can serve as a lead:

Leads MUST be at least a "member" on our contributor ladder to be eligible to hold a leadership role within a SIG.

2bee0a7/sig-governance.md#requirements

This list of requirements seems very vague, and the only real requirement there is to be a community member. I think we can agree that this requirement is not enough on its own.

There's also this point, which is also vague:

SIGs MAY prefer various levels of domain knowledge depending on the role. This should be documented.

I think that the sig chair role is not well-defined, both in terms of the actual role and the authority, responsibility and commitment that comes along with it.

I think we should discuss the following questions regarding sig chairs:

* What are sig chair's responsibilities? Current docs mention `SHOULD define how priorities and commitments are managed`. Does it mean that a chair can decide which features have more/less priority? Does it mean he decides who's assigned to different tasks? Or are we solely talking about managing the sig's meeting and dealing with bureaucracy?

* What is sig chair's authority, if any? Can chairs block a feature proposal? a PR?

* What are the requirements to becoming a chair? Even if we're talking about a role that's completely bureaucratic in nature I'd still expect from chairs to be familiar with the project, have some kind of technical knowledge and to be involved in the organization for a while. The bar should be dramatically higher if a chair's role is technical rather than bureaucratic (e.g. if he's setting priorities, etc, as described in the above bullet) or if the chair has any technical authority.

This is a great topic, but it diverts from this PR focus.
This PR requests to formalize the sig-api by providing a charter.

I am not even sure what is the disagreement about at this stage: That there is a need for such a SIG, the ownership content described in the charter or that its leads are not confirming to some entry criteria?

[iholder101]

This is a great topic, but it diverts from this PR focus.
This PR requests to formalize the sig-api by providing a charter.

This is not accurate, since this PR also assigns SIG chairs.
Therefore I think there's a need to discuss what are the requirements to becoming a sig chair.

I am not even sure what is the disagreement about at this stage: That there is a need for such a SIG, the ownership content described in the charter or that its leads are not confirming to some entry criteria?

From what I've seen above:

• The assigned chairs, specifically what's the entry level to becoming a chair.
• The SIG's scope (as mentioned in this comment). I think that specifically the concerns are:
  • Does sig-api's scope include control-plane components? If not, than which sig should own it?
  • A sig focusing on "everything's API" might be too broad. In addition, in order to be qualified to approve/review every API change of every component on the project the bar should be very high. For these reasons we might want to narrow down and be more focused about the sig's scope.

[EdDev]

This is a great topic, but it diverts from this PR focus.
This PR requests to formalize the sig-api by providing a charter.

This is not accurate, since this PR also assigns SIG chairs. Therefore I think there's a need to discuss what are the requirements to becoming a sig chair.

Given that the criteria already exists, attempting to change the rules now is very odd, especially when previous SIGs had no problem with this.
But, for the sake of just setting the goals and responsibility in place, will the removal of the chairs help in accepting the charter? I.e. will you approve it?
It will be odd, but at least we can have the important thing in.

• The SIG's scope (as mentioned in this comment). I think that specifically the concerns are:

  • Does sig-api's scope include control-plane components? If not, than which sig should own it?
  • A sig focusing on "everything's API" might be too broad. In addition, in order to be qualified to approve/review every API change of every component on the project the bar should be very high. For these reasons we might want to narrow down and be more focused about the sig's scope.

Can you please point me to the specific scope entry that there is disagreement on? Can we word it differently so you will not be concerned about the points you are worried about?

[fabiand]

FWIW - from the process perspective, we could easily make the chairs approvers, but give no ownership to these approvers. We could do this ot underline the advisory role of this group.

We could look, and I'm carefully positive on this, to give SIG API some ownership of few API relatde core directories (not sure which place would be best) to approve (or reject) API (only) changes.

[EdDev]

Can we please continue the discussion on this charter?

[EdDev]

@vladikr , this proposal is not related to api-machinery, it is related to the API governance subproject of sig-architecture.
It is actually a portion of that subproject, as it only focused on the API part.

I see very little value and a risk for a bottleneck in a sig that is only responsible for writing APIs without the knowledge and responsibility of how these APIs affect the rest of the components.

The SIG is not responsable to write APIs, it is responsible to provide guidance and protect the project API, keeping it safe in terms of comparability, dependability and consistency.

IMO the project reached a size that makes it hard for all maintainers/approvers to consider all API concerns and avoid conflict of interest with other concerns (functionality, code quality, delivery due time).

I would expect the SIG-API to evaluate an API change and seek/ask for several alternatives before it is being accepted.
This may be considered a bottleneck, although this charter is not hinting anything about enforcing at this stage. I think it makes sense to be very careful when introducing API changes at this stage, it should be much harder than before, with more discussions taking place.
I think we are not yet in a good position today, although awareness has increased.

[fabiand]

I like the general directoin.

To me the scope if about defining best practice, tools, rules around APIs.
It's not about writing APIs.

Thus maybe the biggest feedback is possibly to adjust the name to conside sig-api-governance.

General +1 on the direction (again ;) ).

[fabiand]

define PRR

[fabiand]

You do not want to "Define … API changes".

Can we reword this? Maybe you want to say that you want to support the community in doing "graceful, fwd and etc changes?"

[fabiand]

To me +1 about the scope

This sig is not implementing APIs, it's rather focused on establishing standards around it - as described below.

Implementing, and maintaining APIs is still up to the other SIG (whoever is providing it), and the machinery is currently owned by sig compute (IIUIC) - but this is separate from this proposed sig.

Btw - one takeaway could be @EdDev @alaypatel07 to call this sig sig-api-governance.

[vladikr]

I like the general directoin.

To me the scope if about defining best practice, tools, rules around APIs. It's not about writing APIs.

Thus maybe the biggest feedback is possibly to adjust the name to conside sig-api-governance.

Does this have to be a sig? At this point, this proposed sig is functionally much different from sigs.

General +1 on the direction (again ;) ).

[EdDev]

Does this have to be a sig? At this point, this proposed sig is functionally much different from sigs.

It can be a subproject under a different SIG, but I do not think we have a sig-architecture as K8s have.
We could start with a SIG and then change it to a subproject.
Do you have a parent SIG you recommend?

[fabiand]

To me a benefit of becoming a sig is: This sig could be declared to have ownership of the API.
To underline the importance and relevant of this sig.

[vladikr]

To me a benefit of becoming a sig is: This sig could be declared to have ownership of the API. To underline the importance and relevant of this sig.

Personally, I don't fully understand what "have ownership of the API" means in practice. To me, the API and the use of it spread across multiple components that need to be viewed together.
Similar to the sig-api-machinery

[vladikr]

Does this have to be a sig? At this point, this proposed sig is functionally much different from sigs.

It can be a subproject under a different SIG, but I do not think we have a sig-architecture as K8s have. We could start with a SIG and then change it to a subproject. Do you have a parent SIG you recommend?

I would strongly prefer this work to be done under a subproject. We spoke about creating a sig-architecture we could replicate this from k8s.

[xpivarc]

Does this have to be a sig? At this point, this proposed sig is functionally much different from sigs.

It can be a subproject under a different SIG, but I do not think we have a sig-architecture as K8s have. We could start with a SIG and then change it to a subproject. Do you have a parent SIG you recommend?

I would strongly prefer this work to be done under a subproject. We spoke about creating a sig-architecture we could replicate this from k8s.

@vladikr Do we have someone interesting to create the sig-architecture? Sounds sane to me.

[fabiand]

The reason why I support sig api is, because Alay and Edy already do the work.

[fabiand]

What do we need to do to move this forward?

[xpivarc]

@alaypatel07 Can we revive this?

[iholder101]

I think that the code-quality committee suggested in #296 might be a good alternative for sig-api.

[EdDev]

I think that the code-quality committee suggested in #296 might be a good alternative for sig-api.

Well, after more than a year of investment in this effort, I can assure you that it has nothing to do with code-quality.

[iholder101]

I think that the code-quality committee suggested in #296 might be a good alternative for sig-api.

Well, after more than a year of investment in this effort, I can assure you that it has nothing to do with code-quality.

Sorry, I meant that like the code-quality issue, a committee is the right form to discuss APIs instead of a SIG.

[lyarwood]

All, I really think we need to land this PR and iterate on the definition within sig-api after. I'm here as I was unable to find any docs for a SIG that I had assumed we had formed months ago....

FWIW I agree with @EdDev that there's enough standalone API code outside the remit of individual SIGs to warrant a standalone group. We could also end up with a WG for specific efforts around the API such as moving to a new version of openAPI etc but I think a SIG with top level / overall ownership of virt-api and staging makes sense.

@alaypatel07 anything I can do to help move this forward? Can you move this out of draft and we can get it merged.

[iholder101]

All, I really think we need to land this PR and iterate on the definition within sig-api after. I'm here as I was unable to find any docs for a SIG that I had assumed we had formed months ago....

I think that the main disagreement here is whether the effort around APIs is suited for a SIG.
I agree this effort is valuable, but agree with @vladikr that a committee or a working-group is a better alternative.

[EdDev]

All, I really think we need to land this PR and iterate on the definition within sig-api after. I'm here as I was unable to find any docs for a SIG that I had assumed we had formed months ago....

I think that the main disagreement here is whether the effort around APIs is suited for a SIG. I agree this effort is valuable, but agree with @vladikr that a committee or a working-group is a better alternative.

I do not think it fits a WG and my interpretation of @vladikr message is to make it a subproject (which is not that different from a SIG).
It looks like @xpivarc also supports something like this.

But maybe the difference between a WG and a subproject was blur at the time.

While the API is cross SIG, there is a specific code path in which the API changes are performed.
Therefore, it fits under ownership of code with the ability in the future to protect this area given an established best-practice recommendations. But at the moment, I would expect no special rights on the codebase, just participation and acceptance that we need to build expertise.

Defining the effort as a SIG or subproject is just wording and nothing more, so I have no problem with converting this to a subproject as long as we create the higher-level SIG. I just think that SIG has a larger scope and I am unsure if we have the capacity to manage one.

I also agree with this comment from @fabiand :

To me the scope if about defining best practice, tools, rules around APIs.
It's not about writing APIs.

Ref: #296 (review)

However, I do not what this management thing to be the cause of not having this effort pushed forward.
If a WG is the wining structure you all agree on, we can start with it.

[kubevirt-bot]

@alaypatel07: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-community-make-generate	38d6e5f	link	true	/test pull-community-make-generate

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.