This is basically a resurrection of #115.
As the result of that issue we decided that the only API of the piper-lib are the steps. Hence everything inside the folder src
is not an API and with that all content in the src
folder can be changed without prior notice and without deprecate something before changing it. In case I change something which is not a step it is - without having APIs - sufficient to grep for the usage of e.g. the method I would like to change, find a way to adapt the callers and that's it.
Now we know that the configuration framework is used from outside. See here.
We have now the situation that we have code we must not change in order not to break the colleagues use cases. Of course we can say: 'Sorry, you used something which is not a API, so it was your fault'. But in fact that is not a fully suitable approach since it makes in fact sense to re-use such common parts like configuration.
IMO it is not a cool approach to have the knowledge about what is re-use and what not having only shared in our minds. This does not scale in case new colleagues entering the project, and it is anyhow error prone since it depends purely on the human factor.
Hence we should find a way to make transparent which is - with good reasons - re-used. With other words, we should think about how we declare an API.
There are - as we all know - several ways. E.g.:
- We keep the current strategy: only the steps from
var
are API, for everything else we do not care.
- Write down a comment for the class/method which is intended to be re-used saying that this method is an API. (Not that cool IMPO, but technically possible)
- Use an
@API
annotation for the class/method
- Define an api package, e.g.
com.sap.piper.api
- [...]
Since we have in fact reasonable re-use we should think about how to deal with that in a transparent way beyond sharing the API only in our minds.
In case we agree on defining an API we should also think about a communication channel used for announcing API changes. As the world keeps on moving there will be the need of deprecate some parts of the API over time. Here we need something in order to able to communicate. But that is another issue.
I would like to outline that the reason for opening this issue is not to be somehow proud of having an API. Having APIs is not an end in itself. The reason why I re-trigger the API discussion is: make life easier for the involved developers.