Update API-onboarding Document to comply with current API Backlog process and Sandbox / Incubated approach

[jgarciahospital]

What type of PR is this?

• enhancement
• cleanup
• documentation

What this PR does / why we need it:

Including modifications for API onboarding document to finalize the inclusion of Sandbox / Incubated way of working.

Pending:

• Validate requirements for Graduated repositories (number of deployments, supporters)
• Validate conditions for archived repositories (number of missed released or months without activity)

Next steps:

• Template for API backlog inclusion (helping in onboarding process)
• Template for Incubation request
• Template for Graduation request

Which issue(s) this PR fixes:

Fixes #173

[hdamker]

@jgarciahospital thanks a lot for the PR! I've reviewed the proposed document and will provide my suggestions in two phases:

1. Changes within the current structure of the document, e.g. on terminology, typos, points which I see slightly different. These I will provide as comments and suggestions as usual review comments
2. Some proposals for restructuring of the document, e.g. an overview of the full lifecycle in the beginning.

After step 1 I would approve this PR and we should aim to get it finally reviewed and merged. The changes for step 2 can be done in a new PR, which I volunteer to create.

[hdamker]

My comments for step 1 mentioned in the previous comment. It might make sense to have a call to explain/discuss them.

[hdamker]

I propose to rename the file to API-Onboarding-and-Lifecycle.md (as already linked within ProjectStructureAndRoles.md)

[hdamker]

Agree to do the renaming in a PR immediately afterwards.

[hdamker]

"Family" is ambiguous, it can be understood as the group of APIs within a repository or the group of APIs which are supervised by a Sub Project. I recommend to organize the list on the level of API Repository, not single APIs.

Suggested change

	| **API [Family] Name** | The name of the API or API family (e.g., "Messaging API Family"). |
	| **API Repository Name** | The name of the API or API family (e.g., "Messaging API(s)"). |

[jgarciahospital]

That is a bit generic if the list is "APIs", since API proposals are at API level. I'm ok on living it at public release level (easier to track).

[hdamker]

See new suggestion to get rid of the "family" term.

[jgarciahospital]

Including small adjustments after internal review.

[jgarciahospital]

Suggested change

A dedicated repository is created for the API under its assigned Sub-Project or as part of a new Sub-Project. The repository structure shall comply with [CAMARA governance guidelines](https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md).

A dedicated Sandbox API Repository is created for the API under its assigned Sub Project or as an independent Sandbox API Repository until incubation phase. The repository structure shall comply with [CAMARA governance guidelines](https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md) and will be derived from the [Template_API_Repository](https://github.com/camaraproject/Template_API_Repository).

[hdamker]

That's seem to be almost the same suggestion then in my comment #171 (comment).

Just the note that as an alternative to incubation there is also the option that an independent Sandbox will be adopted by an existing Sub Project even before incubation. But that's maybe an edge case which we don't need to describe here.

[jgarciahospital]

@hdamker thanks for the review. I have included couple of pending changes after internal review, let me review in detail your proposals during next weekend.

[hdamker]

@hdamker thanks for the review. I have included couple of pending changes after internal review, let me review in detail your proposals during next weekend.

@jgarciahospital short comments on the pending changes. wish you a nice (and/or productive) weekend!

[jgarciahospital]

@hdamker Document cleaned and pending for first phase merging. Pending comments/discussions will be handled in second phase.

[hdamker]

A few suggestions for changes I would like to see already in this interim version to be more consistent with the other governance documents.

[hdamker]

See new suggestion to get rid of the "family" term.

[hdamker]

Agree to do the renaming in a PR immediately afterwards.

[hdamker]

Thanks for taking all my suggestions. Fine with this interim version, looking forward to the restructuring.