RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Hello Carl, > -Original Message- > From: Carl Marcum [mailto:cmar...@apache.org] > Sent: Tuesday, October 19, 2021 1:13 PM > To: dev@openoffice.apache.org > Subject: Re: API doc on web site [Was: Accessing the comment > object (annotation) in Draw/Impress via API] > >> Actually we do provide updated documentation included in > the SDK with > >> each convenience binary release. > >> It can be found on Linux at > >> /opt/openoffice4/sdk/docs/common/ref/module-ix.html > >> if the SDK is installed. > >> > >> Knowing that we can't make API changes like adding or deprecating > >> methods or things like that in a minor version change, > > Is this a principle that _all_ those involved in releases > will also _reliably_ follow? > > It's up to us to inform new contributors who may make such a > mistake if > it were to happen. yes, but ... As far as I know, only the PMC has the right to decide about the release of a release - so will the PMC reliably support the mentioned principle (='API changes not in a minor release')? I would appreciate a clear "yes" or "no" on this. And please allow me to say that the current formal minor release of AOO is "4.1", so, respecting the implied principle, a change to the API is thus not allowed until version 5.0.0. greetings, Jörg - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
Hi Jörg, On 10/19/21 4:26 AM, Jörg Schmidt wrote: -Original Message- From: Carl Marcum [mailto:cmar...@apache.org] Sent: Tuesday, October 19, 2021 3:59 AM To: dev@openoffice.apache.org Subject: Re: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API] Hi All, On 10/17/21 5:17 PM, Peter Kovacs wrote: Hi Jörg, On 17.10.21 19:48, Jörg Schmidt wrote: Hello Peter, -Original Message- From: Peter Kovacs [mailto:pe...@apache.org] Sent: Sunday, October 17, 2021 11:27 AM To: dev@openoffice.apache.org Subject: Re: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API] Hi Jörg, I am not sure what you refer to. I refer to the fact that changes in the API documentation are marked in time (the typical entry is "since ..."), so that the API documentation can be used in practice for all program versions. I think we are on the same page if we want to change the API, but I think this is not the topic. The documentation has no influence on backward compatibility. right. What I am referring to is only that we should not make changes if the QA is not 100% guaranteed. And what I currently experience is that there is a tiny(!) problem in the API documentation, but immediately demanded now to regularly renew the documentation routinely. Again this is relevant if we change the API itself. Explain to me bitterly where there are at all changes in the API that would make it necessary to update the documentation inflationary frequently? I follow every release carefully, only from API changes I have not noticed for years. The API Documentation is extracted from the Code. For example the comment in http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun /star/modules.idl?r=d1766043#83 does have an impact on the web page: https://www.openoffice.org/api/docs/common/ref/com/sun/star/of fice/module-ix.html I hope you see both documentations are linked. So when do we update the documentation on the web site? Currently we will never update the web site, and the danger is that if we change a comment in the documentation it will not end up on the website.. So Arrigos Idea is to update with each release. This would keep the documentation on the web in sync with the latest Code released for this API Version (Which should roughly correspond with the major release). It makes sense to publish on the website which Code the extraction has been taken from and what Versions the Documentation relates to. On an API Change, QA and documentation Versions need to be discussed. But we can discuss this when we get near to a API Change. I think until then we have done some steps in respect of QA. Carl is working on improvements, and I would like to try if we can establish a UI check with UI Path or similar tool. All the best Peter Actually we do provide updated documentation included in the SDK with each convenience binary release. It can be found on Linux at /opt/openoffice4/sdk/docs/common/ref/module-ix.html if the SDK is installed. Knowing that we can't make API changes like adding or deprecating methods or things like that in a minor version change, Is this a principle that _all_ those involved in releases will also _reliably_ follow? It's up to us to inform new contributors who may make such a mistake if it were to happen. On the whole question of API and documentation, I would like to make a general appeal to all of us: The fact that OpenOffice could not be displaced by LibreOffice is largely due to the good quality of OO. We must do everything we can to preserve this quality and not compromise in this regard. In this context, we must also be ready to examine, critically discuss and improve our activities again and again. I very much agree. Best regards, Carl Jörg - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
RE: API doc on web site [Was: Accessing the comment object (annotation) in Draw/Impress via API]
> -Original Message- > From: Carl Marcum [mailto:cmar...@apache.org] > Sent: Tuesday, October 19, 2021 3:59 AM > To: dev@openoffice.apache.org > Subject: Re: API doc on web site [Was: Accessing the comment > object (annotation) in Draw/Impress via API] > > Hi All, > > On 10/17/21 5:17 PM, Peter Kovacs wrote: > > Hi Jörg, > > > > On 17.10.21 19:48, Jörg Schmidt wrote: > >> Hello Peter, > >> > >>> -Original Message- > >>> From: Peter Kovacs [mailto:pe...@apache.org] > >>> Sent: Sunday, October 17, 2021 11:27 AM > >>> To: dev@openoffice.apache.org > >>> Subject: Re: API doc on web site [Was: Accessing the comment > >>> object (annotation) in Draw/Impress via API] > >>> > >>> Hi Jörg, > >>> > >>> > >>> I am not sure what you refer to. > >> I refer to the fact that changes in the API documentation > are marked > >> in time (the typical entry is "since ..."), so that the API > >> documentation can be used in practice for all program versions. > > I think we are on the same page if we want to change the API, but I > > think this is not the topic. > >>> The documentation has no > >>> influence on > >>> backward compatibility. > >> right. > >> > >> What I am referring to is only that we should not make > changes if the > >> QA is not 100% guaranteed. And what I currently experience is that > >> there is a tiny(!) problem in the API documentation, but > immediately > >> demanded now to regularly renew the documentation routinely. > > Again this is relevant if we change the API itself. > >> Explain to me bitterly where there are at all changes in > the API that > >> would make it necessary to update the documentation inflationary > >> frequently? > >> I follow every release carefully, only from API changes I have not > >> noticed for years. > > > > The API Documentation is extracted from the Code. > > > > For example the comment in > > > > > http://opengrok.openoffice.org/xref/aoo41x/main/offapi/com/sun > /star/modules.idl?r=d1766043#83 > > > > > > does have an impact on the web page: > > > > > https://www.openoffice.org/api/docs/common/ref/com/sun/star/of > fice/module-ix.html > > > > > > I hope you see both documentations are linked. So when do we update > > the documentation on the web site? > > > > Currently we will never update the web site, and the danger > is that if > > we change a comment in the documentation it will not end up on the > > website.. > > > > So Arrigos Idea is to update with each release. This would keep the > > documentation on the web in sync with the latest Code released for > > this API Version (Which should roughly correspond with the major > > release). > > > > It makes sense to publish on the website which Code the > extraction has > > been taken from and what Versions the Documentation relates to. > > > > On an API Change, QA and documentation Versions need to be > discussed. > > But we can discuss this when we get near to a API Change. I think > > until then we have done some steps in respect of QA. > > > > Carl is working on improvements, and I would like to try if we can > > establish a UI check with UI Path or similar tool. > > > > All the best > > > > Peter > > > > > > Actually we do provide updated documentation included in the SDK with > each convenience binary release. > It can be found on Linux at > /opt/openoffice4/sdk/docs/common/ref/module-ix.html > if the SDK is installed. > > Knowing that we can't make API changes like adding or deprecating > methods or things like that in a minor version change, Is this a principle that _all_ those involved in releases will also _reliably_ follow? On the whole question of API and documentation, I would like to make a general appeal to all of us: The fact that OpenOffice could not be displaced by LibreOffice is largely due to the good quality of OO. We must do everything we can to preserve this quality and not compromise in this regard. In this context, we must also be ready to examine, critically discuss and improve our activities again and again. Jörg - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
