[docs][tc][infra] what to do with developer.openstack.org and api-site?
The website developer.openstack.org has the tagline "Development resources for OpenStack clouds" and hosts development and API information, especially: * An index page * The OpenStack api-guide * The document "Writing Your First OpenStack Application" ("firstapp guide") * The individual api-guides and api-references which are published from the individual projects like Nova or Keystone. The index page, the OpenStack api-guide and the document "Writing your first OpenStack Application" are hosted in the api-site repository which was formerly part of the docs team but is now orphaned. Let's look at the content hosted in api-site repository * The index page needs little updates * The OpenStack Api-Guide: This is a small guide that needs little maintenance (when projects create/retire API versions) * Writing your first OpenStack Application: This was never finished and only covers a few programming language, it's dead. With moving the repo out of docs (see https://review.opendev.org/485249 for change), the hope was that somebody took it over - but this did not happen. We have an official entry point for OpenStack's development resources and it is served by api-site repo and I suggest we look at the situation and solve it fully. I see the following options: 1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide. 2) Fully revitialize the repo and have it owned by an official team or SIG (this means reverting parts of https://review.opendev.org/485249/) 3) Retire the document "Writing your first OpenStack Application", and unretire api-site and have it owned by some official team/SIG. Any other options? What shall we do? Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, D 90409 Nürnberg GF: Nils Brauckmann, Felix Imendörffer, Enrica Angelone, HRB 247165 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
2) Fully revitialize the repo and have it owned by an official team or SIG (this means reverting parts of https://review.opendev.org/485249/)
3) Retire the document "Writing your first OpenStack Application", and unretire api-site and have it owned by some official team/SIG.
Any other options? What shall we do?
Thanks Andreas for raising this. As an extra data point, my long-term plan was to have SDKs and CLIs properly listed in the Software pages under SDKs[1], including third-party ones in their own subtab, all driven from the osf/openstack-map repository[2]. With that in mind, I think it would make sense to look into retiring developer.openstack.org, and move docs to docs.openstack.org. We could also revive https://www.openstack.org/appdev/ and use it as the base landing page to direct application-side people to the various pieces. [1] https://www.openstack.org/software/project-navigator/sdks [2] https://opendev.org/osf/openstack-map/ -- Thierry Carrez (ttx)
On Mon, 2019-07-15 at 11:50 +0200, Thierry Carrez wrote:
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
2) Fully revitialize the repo and have it owned by an official team or SIG (this means reverting parts of https://review.opendev.org/485249/)
3) Retire the document "Writing your first OpenStack Application", and unretire api-site and have it owned by some official team/SIG.
Any other options? What shall we do?
Thanks Andreas for raising this.
As an extra data point, my long-term plan was to have SDKs and CLIs properly listed in the Software pages under SDKs[1], including third-party ones in their own subtab, all driven from the osf/openstack-map repository[2].
With that in mind, I think it would make sense to look into retiring developer.openstack.org, i use https://developer.openstack.org/api-ref/compute/ almost daily so unless we host the api ref somwhere else and put redirect in place i would hope we can keep this inplace. if we move it under docs like the config stuff https://docs.openstack.org/nova/latest/configuration/config.html or somewhere else that is fine but i fine it very useful to be able to link the rendered api docs to people on irc that ask questions.
i can obviosly point peple to github https://github.com/openstack/nova/blob/master/api-ref/source/servers.inc but unlike the configs the api ref is much less readable with out rendering it with sphinx
and move docs to docs.openstack.org. We could also revive https://www.openstack.org/appdev/ and use it as the base landing page to direct application-side people to the various pieces.
[1] https://www.openstack.org/software/project-navigator/sdks [2] https://opendev.org/osf/openstack-map/
---- On Mon, 15 Jul 2019 23:28:33 +0900 Sean Mooney <smooney@redhat.com> wrote ----
On Mon, 2019-07-15 at 11:50 +0200, Thierry Carrez wrote:
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
2) Fully revitialize the repo and have it owned by an official team or SIG (this means reverting parts of https://review.opendev.org/485249/)
3) Retire the document "Writing your first OpenStack Application", and unretire api-site and have it owned by some official team/SIG.
Any other options? What shall we do?
Thanks Andreas for raising this.
As an extra data point, my long-term plan was to have SDKs and CLIs properly listed in the Software pages under SDKs[1], including third-party ones in their own subtab, all driven from the osf/openstack-map repository[2].
With that in mind, I think it would make sense to look into retiring developer.openstack.org, i use https://developer.openstack.org/api-ref/compute/ almost daily so unless we host the api ref somwhere else and put redirect in place i would hope we can keep this inplace.
Yeah, this link is used very frequently by many developers as well as by users. Redirect is something much needed for this site. -gmann
if we move it under docs like the config stuff https://docs.openstack.org/nova/latest/configuration/config.html or somewhere else that is fine but i fine it very useful to be able to link the rendered api docs to people on irc that ask questions.
i can obviosly point peple to github https://github.com/openstack/nova/blob/master/api-ref/source/servers.inc but unlike the configs the api ref is much less readable with out rendering it with sphinx
and move docs to docs.openstack.org. We could also revive https://www.openstack.org/appdev/ and use it as the base landing page to direct application-side people to the various pieces.
[1] https://www.openstack.org/software/project-navigator/sdks [2] https://opendev.org/osf/openstack-map/
---- On Mon, 15 Jul 2019 18:50:05 +0900 Thierry Carrez <thierry@openstack.org> wrote ----
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
+1 on option 1. openstack api-guides (not the individual projects api-guides) make more sense under os-api-ref which is nothing but overall openstack APIs state and less maintenance effort as you mentioned. api-references content is on project side ./api-ref/source. Do you mean to move them to doc/source ? or cannot we host docs.openstack.org from the same existing ./api-ref/source location? -gmann
2) Fully revitialize the repo and have it owned by an official team or SIG (this means reverting parts of https://review.opendev.org/485249/)
3) Retire the document "Writing your first OpenStack Application", and unretire api-site and have it owned by some official team/SIG.
Any other options? What shall we do?
Thanks Andreas for raising this.
As an extra data point, my long-term plan was to have SDKs and CLIs properly listed in the Software pages under SDKs[1], including third-party ones in their own subtab, all driven from the osf/openstack-map repository[2].
With that in mind, I think it would make sense to look into retiring developer.openstack.org, and move docs to docs.openstack.org. We could also revive https://www.openstack.org/appdev/ and use it as the base landing page to direct application-side people to the various pieces.
[1] https://www.openstack.org/software/project-navigator/sdks [2] https://opendev.org/osf/openstack-map/
-- Thierry Carrez (ttx)
On 16/07/2019 14.26, Ghanshyam Mann wrote:
---- On Mon, 15 Jul 2019 18:50:05 +0900 Thierry Carrez <thierry@openstack.org> wrote ----
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
+1 on option 1.
openstack api-guides (not the individual projects api-guides) make more sense under os-api-ref which is nothing but overall openstack APIs state and less maintenance effort as you mentioned.
I propose move it to openstack-manuals instead of os-api-ref to make publishing easier. os-api-ref is a tool used by others.
api-references content is on project side ./api-ref/source. Do you mean to move them to doc/source ? or cannot we host docs.openstack.org from the same existing ./api-ref/source location?
The idea some time ago was to move them to doc/source But short-term we can just change the publishing jobs to publish to docs.openstack.org/api-reference instead of developer.openstack.org/api-reference, Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
---- On Tue, 16 Jul 2019 21:35:43 +0900 Andreas Jaeger <aj@suse.com> wrote ----
On 16/07/2019 14.26, Ghanshyam Mann wrote:
---- On Mon, 15 Jul 2019 18:50:05 +0900 Thierry Carrez <thierry@openstack.org> wrote ----
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
+1 on option 1.
openstack api-guides (not the individual projects api-guides) make more sense under os-api-ref which is nothing but overall openstack APIs state and less maintenance effort as you mentioned.
I propose move it to openstack-manuals instead of os-api-ref to make publishing easier. os-api-ref is a tool used by others.
I am ok to move under openstack-manual also. Though we do not know the future home of openstack-manual as docs team is moving towards SIG. But where ever it will go, 'OpenStack api guide' can go with this.
api-references content is on project side ./api-ref/source. Do you mean to move them to doc/source ? or cannot we host docs.openstack.org from the same existing ./api-ref/source location?
The idea some time ago was to move them to doc/source
But short-term we can just change the publishing jobs to publish to docs.openstack.org/api-reference instead of developer.openstack.org/api-reference,
Yeah, I remember there were no clear consesus of moving the api-ref/source to doc/source so that might take time. publishing from api-ref/source as short term options looks good to me. Thanks for initiating this discussion and caring about these sites. -gmann
Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 16/07/2019 14.49, Ghanshyam Mann wrote:
[...] I am ok to move under openstack-manual also. Though we do not know the future home of openstack-manual as docs team is moving towards SIG. But where ever it will go, 'OpenStack api guide' can go with this.
I think a SIG can own repositories, so there's no technical blocker for that, Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
Andreas Jaeger wrote:
On 16/07/2019 14.49, Ghanshyam Mann wrote:
[...] I am ok to move under openstack-manual also. Though we do not know the future home of openstack-manual as docs team is moving towards SIG. But where ever it will go, 'OpenStack api guide' can go with this.
I think a SIG can own repositories, so there's no technical blocker for that,
Yes a SIG (and any other workgroup) can own git repositories. Only deliverables (groups of repositories released together as part of the OpenStack release) need to be owned by a project team. -- Thierry Carrez (ttx)
On Tue, 2019-07-16 at 14:35 +0200, Andreas Jaeger wrote:
On 16/07/2019 14.26, Ghanshyam Mann wrote:
---- On Mon, 15 Jul 2019 18:50:05 +0900 Thierry Carrez <thierry@openstack.org> wrote ----
Andreas Jaeger wrote:
[...] I see the following options:
1) Retiring developer.openstack.org completely, this would mean we would host the api-guides and api-references on docs.openstack.org (perhaps with moving them into doc/source). If we go down this road, we need to discuss what this means (redirects) and what to do with the Api-Guide and the FirstApp guide.
+1 on option 1.
openstack api-guides (not the individual projects api-guides) make more sense under os-api-ref which is nothing but overall openstack APIs state and less maintenance effort as you mentioned.
I propose move it to openstack-manuals instead of os-api-ref to make publishing easier. os-api-ref is a tool used by others.
api-references content is on project side ./api-ref/source. Do you mean to move them to doc/source ? or cannot we host docs.openstack.org from the same existing ./api-ref/source location?
The idea some time ago was to move them to doc/source
Note that we can't do this because the API reference guides (and release notes, since reno does that for us) shouldn't be versioned by release, unlike the rest of the docs.
But short-term we can just change the publishing jobs to publish to docs.openstack.org/api-reference instead of developer.openstack.org/api-reference,
Stephen
Andreas
>From the feedback so far, let me refine the proposal:
* Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o
* Kill "Writing Your First OpenStack Application" document
* Publish all in-tree api-references and api-guides on
docs.openstack.org instead of developer.o.o
* List SDKs and CLIs on the software page
* Add redirects on developer.openstack.org for moved documents
* Once the above is all done, kill api-site (or leave it up for some
time in frozen state with redirects).
I can take care of most steps (exception is software page - this is for
Thierry, correct?),
Andreas
--
Andreas Jaeger aj@suse.com Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On Tue, 2019-07-16 at 16:17 +0200, Andreas Jaeger wrote:
From the feedback so far, let me refine the proposal: * Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o * Kill "Writing Your First OpenStack Application" document * Publish all in-tree api-references and api-guides on docs.openstack.org instead of developer.o.o * List SDKs and CLIs on the software page * Add redirects on developer.openstack.org for moved documents * Once the above is all done, kill api-site (or leave it up for some time in frozen state with redirects).
This all make sense to me, though the crucial part is those redirects, of course. I don't know how much time I can spare but let me know if you need help with anything. Stephen
I can take care of most steps (exception is software page - this is for Thierry, correct?),
Andreas
On Tue, 2019-07-16 at 16:17 +0200, Andreas Jaeger wrote:
From the feedback so far, let me refine the proposal: * Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o * Kill "Writing Your First OpenStack Application" document * Publish all in-tree api-references and api-guides on docs.openstack.org instead of developer.o.o * List SDKs and CLIs on the software page * Add redirects on developer.openstack.org for moved documents it looks like my reply earlirer got droped when i rebotted my laptop. just wanted to say i use the config referecnce https://docs.openstack.org/nova/latest/configuration/config.html and the api doc https://developer.openstack.org/api-ref/compute/ almost daily espcially when helping people on irc.
as long as we continue to have a rendered copy of them hosted that is fine and idealy with redirect as you are suggesting. unlike some of the other docs the api-ref is much harder to consume in plain text form the git repo or via github https://github.com/openstack/nova/blob/master/api-ref/source/servers.inc or opendev https://opendev.org/openstack/nova/src/branch/master/api-ref/source/servers.... although if it wasnt fro the lag the opendev version is much better then the way github tries to render it as markdown. it sound like the plan will contiue to preseve a hosted copy of the api refes so i guess that is my main request.
* Once the above is all done, kill api-site (or leave it up for some time in frozen state with redirects).
I can take care of most steps (exception is software page - this is for Thierry, correct?),
Andreas
On 7/16/19 4:39 PM, Sean Mooney wrote:
On Tue, 2019-07-16 at 16:17 +0200, Andreas Jaeger wrote:
From the feedback so far, let me refine the proposal: * Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o * Kill "Writing Your First OpenStack Application" document * Publish all in-tree api-references and api-guides on docs.openstack.org instead of developer.o.o * List SDKs and CLIs on the software page * Add redirects on developer.openstack.org for moved documents it looks like my reply earlirer got droped when i rebotted my laptop. just wanted to say i use the config referecnce https://docs.openstack.org/nova/latest/configuration/config.html and the api doc https://developer.openstack.org/api-ref/compute/ almost daily espcially when helping people on irc.
Yes, the steps above will ensure that we publish to https://docs.openstack.org/api-ref/compute/ and set up a redirect to the new location. So, your bookmarks will continue to work - and going forward, I recommend updating them ;)
as long as we continue to have a rendered copy of them hosted that is fine and idealy with redirect as you are suggesting. unlike some of the other docs the api-ref is much harder to consume in plain text form the git repo or via github https://github.com/openstack/nova/blob/master/api-ref/source/servers.inc or opendev https://opendev.org/openstack/nova/src/branch/master/api-ref/source/servers.... although if it wasnt fro the lag the opendev version is much better then the way github tries to render it as markdown.
it sound like the plan will contiue to preseve a hosted copy of the api refes so i guess that is my main request.
Correct, Andreas
* Once the above is all done, kill api-site (or leave it up for some time in frozen state with redirects).
I can take care of most steps (exception is software page - this is for Thierry, correct?),
Andreas
-- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
---- On Tue, 16 Jul 2019 23:17:40 +0900 Andreas Jaeger <aj@suse.com> wrote ----
From the feedback so far, let me refine the proposal: * Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o * Kill "Writing Your First OpenStack Application" document * Publish all in-tree api-references and api-guides on docs.openstack.org instead of developer.o.o * List SDKs and CLIs on the software page * Add redirects on developer.openstack.org for moved documents * Once the above is all done, kill api-site (or leave it up for some time in frozen state with redirects).
I can take care of most steps (exception is software page - this is for Thierry, correct?),
+1 on all. Thanks again. -gmann
Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Mary Higgins, Sri Rasiah HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 16/07/2019 16.17, Andreas Jaeger wrote:
From the feedback so far, let me refine the proposal: * Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o * Kill "Writing Your First OpenStack Application" document * Publish all in-tree api-references and api-guides on docs.openstack.org instead of developer.o.o * List SDKs and CLIs on the software page * Add redirects on developer.openstack.org for moved documents * Once the above is all done, kill api-site (or leave it up for some time in frozen state with redirects).
I can take care of most steps (exception is software page - this is for Thierry, correct?),
I've started pushing changes with topic retire-api-site, https://review.opendev.org/#/q/topic:retire-api-site Will WIP for two days, Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, D 90409 Nürnberg GF: Nils Brauckmann, Felix Imendörffer, Enrica Angelone, HRB 247165 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
Let me add some more tags and cross-post to user-committee and reword. The api-site repo is orphaned, it is used to publish the content of developer.openstack.org. I propose now the following actions: * Move OpenStack API-Guide to openstack-manuals repo and publish to docs.o.o (currently published at https://developer.openstack.org/api-guide/quick-start/) * Add a redirect for this on developer.o.o * Kill the "Writing Your First OpenStack Application" document, since it's completely dead and outdated (last non-trivial change was 22nd February 2017). This is currently published to https://developer.openstack.org/firstapp-libcloud/ and https://developer.openstack.org/firstapp-shade/ * Publish all api-guide and api-ref documents to docs.openstack.org, add redirects for them on developer.openstack.org * List SDKs and CLIs on the software page on www.openstack.org (Thierry plans to do this) * Remove landing page from developer.o.o, add redirects. * After some time, retire developer.o.o and api-site repo completely. I've started pushing changes with topic retire-api-site, https://review.opendev.org/#/q/topic:retire-api-site Will WIP until Monday, 22nd of July. If any team wants to adopt api-site completely, or parts of it, please speak up, happy to help a hand-over - or wait a bit longer if further discussion is needed, Andreas -- Andreas Jaeger aj@suse.com Twitter: jaegerandi SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, D 90409 Nürnberg GF: Nils Brauckmann, Felix Imendörffer, Enrica Angelone, HRB 247165 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
participants (5)
-
Andreas Jaeger
-
Ghanshyam Mann
-
Sean Mooney
-
Stephen Finucane
-
Thierry Carrez