Re: [openstack-dev] [Solum] Create a source repo for the API specification?
- Original Message - I like this idea. I'd also propose that the format of the specification be something machine-readable, such as API-Blueprint (a simple subset of markdown, apiblueprint.org , also what apiary uses, if you've ever seen that) or RAML (a more structured YAML-based syntax, raml.org ). API-Blueprint is closer to what the keystone document uses. Making the documentation machine-readable means that it's much easier to verify that, in practice, the implementation of an API matches its specification and documentation, which is a problem that plagues many OpenStack projects right now. At the meeting today we discussed putting together an initial seed based around the proposed API and based mostly on the identity-api work. Are folks ok with api-blueprint [1] [1] http://apiblueprint.org ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Solum] Create a source repo for the API specification?
- Original Message - On Sat, Nov 2, 2013 at 4:55 PM, Christopher Armstrong chris.armstr...@rackspace.com wrote: On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes jaypi...@gmail.com wrote: Hi all, One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community. One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications: https://github.com/openstack/ identity-api When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made: https://review.openstack.org/# /c/54215/10 I'd like to propose that Solum do the same: have a separate source repository for the API specification. Thoughts? -jay I like this idea. I'd also propose that the format of the specification be something machine-readable, such as API-Blueprint (a simple subset of markdown, apiblueprint.org , also what apiary uses, if you've ever seen that) or RAML (a more structured YAML-based syntax, raml.org ). API-Blueprint is closer to what the keystone document uses. Making the documentation machine-readable means that it's much easier to verify that, in practice, the implementation of an API matches its specification and documentation, which is a problem that plagues many OpenStack projects right now. Hi all, I wouldn't expect you to know this unless you read minds, but we had a Summit session last week and a long email thread with all the PTLs prior to the Summit, and we decided to move all API specs into the repositories of the project itself, and stop maintaining separate spec repos. The Etherpad is here: https://wiki.openstack.org/wiki/Summit/Icehouse/Etherpads We are working on a document to describe how to document your API both for future end-users and for current devs wanting to write to the specified needs of the API. Stay tuned to all the bat channels for that. Happy to discuss further, but after 2 years, it's time to make some changes, and we worked hard to build consensus for the 10+ APIs we have in OpenStack. Thanks, Anne While waiting for that to manifest, pandoc can do a reasonably good mediawiki - markdown conversion. Here's an example of the current API doc transliterated: https://gist.github.com/smarterclayton/7458182. We can either check in a md format (for easy GitHub viewing) version into solum/ and iterate on that via code review, or hold off and iterate on the wiki page as it stands today. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [Solum] Create a source repo for the API specification?
Hi all, One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community. One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications: https://github.com/openstack/identity-api When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made: https://review.openstack.org/#/c/54215/10 I'd like to propose that Solum do the same: have a separate source repository for the API specification. Thoughts? -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Solum] Create a source repo for the API specification?
On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes jaypi...@gmail.com wrote: Hi all, One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community. One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications: https://github.com/openstack/identity-api When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made: https://review.openstack.org/#/c/54215/10 I'd like to propose that Solum do the same: have a separate source repository for the API specification. Thoughts? -jay I like this idea. I'd also propose that the format of the specification be something machine-readable, such as API-Blueprint (a simple subset of markdown, apiblueprint.org, also what apiary uses, if you've ever seen that) or RAML (a more structured YAML-based syntax, raml.org). API-Blueprint is closer to what the keystone document uses. Making the documentation machine-readable means that it's much easier to verify that, in practice, the implementation of an API matches its specification and documentation, which is a problem that plagues many OpenStack projects right now. -- IRC: radix Christopher Armstrong Rackspace ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Solum] Create a source repo for the API specification?
Jay, On Nov 2, 2013, at 2:39 PM, Jay Pipes jaypi...@gmail.com wrote: Hi all, One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community. One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications: https://github.com/openstack/identity-api When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made: https://review.openstack.org/#/c/54215/10 I'd like to propose that Solum do the same: have a separate source repository for the API specification. Thoughts? -jay This strikes me as a way to make the API design process more collaborative, particularly in the way that it allows us to get a picture of perspectives from a wide range of contributors, and the ability to to make line-level comments like we do with source code. I think that will be much more powerful than what we have today with the wiki page. Thanks for suggesting it Jay! Adrian ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Solum] Create a source repo for the API specification?
+1 - with the level of interest among existing vendors I think this will help others who want to be API compatible with Solum (above and beyond normal benefits) On Nov 2, 2013, at 5:48 PM, Jay Pipes jaypi...@gmail.com wrote: Hi all, One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community. One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications: https://github.com/openstack/identity-api When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made: https://review.openstack.org/#/c/54215/10 I'd like to propose that Solum do the same: have a separate source repository for the API specification. Thoughts? -jay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Solum] Create a source repo for the API specification?
+1 Couldn't agree more. Christopher Armstrong chris.armstr...@rackspace.com wrote: On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes jaypi...@gmail.commailto:jaypi...@gmail.com wrote: Hi all, One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community. One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications: https://github.com/openstack/identity-api When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made: https://review.openstack.org/#/c/54215/10 I'd like to propose that Solum do the same: have a separate source repository for the API specification. Thoughts? -jay I like this idea. I'd also propose that the format of the specification be something machine-readable, such as API-Blueprint (a simple subset of markdown, apiblueprint.orghttp://apiblueprint.org, also what apiary uses, if you've ever seen that) or RAML (a more structured YAML-based syntax, raml.orghttp://raml.org). API-Blueprint is closer to what the keystone document uses. Making the documentation machine-readable means that it's much easier to verify that, in practice, the implementation of an API matches its specification and documentation, which is a problem that plagues many OpenStack projects right now. -- IRC: radix Christopher Armstrong Rackspace ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
