[Discuss] Process on changes to the package-spec

[ruflin]

The package-spec has become a central part of everything around packages, integrations, Fleet, Elastic Agent. Any change or addition to the package-spec can have wide ranging consequences. This issue is to discuss on how we make changes to the package-spec and ensure it does not have any unexpected side effects.

To better explain the problem I'll use an example. The addition of a new asset type like elasticsearch transform affects many parts. The package-registry must know how to delivery it, Kibana / Fleet must know how to update / downgrade / install / remove the asset, it must fit into the indexing strategy, elastic-package must know how to test it. So before adding a new assets, it must be checked how it should be added and which parts are effected by it.

The above applies to addition of all asset types but also to changes / additions to the manifest files. How do we ensure nothing breaks? At the same time, we should ensure that the package-spec stays open for contributions from everyone and don't put too much burden on potential changes.

One idea to start with is having a detailed checklist when modifying the package-spec. Any change should go through this checklist. In addition, it would be nice to have experts from each area that can be pinged for help. Someone wanting to add a new asset for Kibana might not have all the expertise on how this affects elastic-package. So each area could have an expert that can be pinged.

[ycombinator]

Thanks for starting this much-needed discussion, @ruflin.

At a high level, I would say the process looks something like this:

1. Whenever there's a potential change that impacts the package spec, this change must be proposed in an issue in the package-spec repository. This gives us an opportunity to understand which parts of the stack might be impacted by this change and pull in relevant experts to get their opinions. The initial proposal should cover these areas:

   • what problem the proposal is solving. This provides context and could help shape the solution.
   • where the solution will need to be implemented, aka which parts of the stack will be impacted. Its okay if the initial proposal doesn't get this 100% right; the discussion in the proposal issue will help clarify this. But having some idea initially will help get the ball rolling in terms of pulling in the right people for the discussion.

2. Once we have consensus on the proposal issue, we modify the issue description to include an ordered checklist of tasks that need to be resolved to make the change happen in a safe way. For example, maybe Kibana needs to implement support for a new property in the spec first, then only when the support is implemented, the spec can itself be modified, which would then allow packages to define this property and have these packages still be valid. At this point the proposal issue serves as a meta issue for the safe implementation of the change.

3. We file issues in each of the repositories corresponding to the checklist items and update the checklist with links to these issues.

4. No single PR may close the proposal issue. But as these PRs get resolved, the corresponding checklist item must be checked off. The proposal/meta issue is closed when all items are checked off.

To facilitate the above process we can:

• document it in the contributing guide of this repository,
• create a GitHub issue template for proposals which includes a link to the aforementioned contributing guide section + a commented-out list of components that can be used to build the ordered checklist (this way we don't easily forget to consider the impact on any component).

Thoughts?

[ruflin]

++ on your proposal @ycombinator

[ycombinator]

@mtojek do you have any thoughts?

[mtojek]

Sorry I missed your response.

create a GitHub issue template for proposals

This is the right place to become a checklist, agree here.

++ on my side too. Nice work!

[ycombinator]

Thanks both of you. I will proceed with a PR to document this process in the CONTRIBUTING.md file + create an issue template for proposals.

[ruflin]

Great, form there we can always iterate.