The Allura API, to me, includes: * REST API * Supported entry points / entry-point groups * Provider API classes in allura.lib.plugin * Theme API (provider class, and macros) * Application class * Artifact class and associated subclasses / mixins * Events API (supported events, and @event_handler decorator) * allura.lib.package_path_loader * allura.lib.spam * Task API (@task decorator, post() method, and MonQTask model)
Some of this is currently documented in the API Documentation section of the docs, but we need fill it out by adding docstrings to the appropriate classes and methods where missing. If we don't have tickets for documenting each of these so that at a minimum the methods of the base class for each are listed, we should create them. Any change that would require updating the docs on any of these would constitute an API change, whether major or minor. On Mon, Dec 16, 2013 at 5:54 PM, Dave Brondsema <[email protected]> wrote: > I agree, it's more than the REST API. I think it includes the core Allura > package to the extent that its used to make extensions (tools, themes, auth > providers, etc). But like you say, its hard to exactly define that. We > don't > really distinguish between Allura methods that are meant for other > packages to > use, and those that are internal. > > On 12/13/13 10:01 AM, Tim Van Steenburgh wrote: > > I'm +1 on following http://semver.org. My biggest question is how to > define our public API. From the site: > > > > "Software using Semantic Versioning MUST declare a public API. This API > could be declared in the code itself or exist strictly in documentation. > However it is done, it should be precise and comprehensive." > > > > Is Allura's public API more than it's actual REST API? Seems like it, > although it'll be tedious to precisely define. Thoughts on this? > > > > > > On Friday, December 13, 2013 at 12:31 AM, Dave Brondsema wrote: > > > >> What versioning system do we want to use? Major.Minor.Patch as > described at > >> http://semver.org/? Our next release would be 1.1.0 then. I don't > think we > >> have many API-breaking changes in general, so we'd probably be in a > 1.X.0 > >> pattern for quite a while. > >> (Although, in a sense, our recent unreleased change to move the CSRF > token from > >> JS to server-side was backwards incompatible. It requires 3rd-party > apps to add > >> it to their forms, unless they use EasyWidgets. This broke the > ForgePastebin > >> app. It's not a sweeping change, but a small incompatibility > nonetheless) > >> > >> On 12/10/13 3:28 PM, Cory Johns wrote: > >>> Agreed. Having all of our current importers enabled seems like a good > spot > >>> to release, as does activity streams. > >>> > >>> I think we should try not to ever go more than 2 months without doing a > >>> release, and I might even say 1 release per month might be a good > target > >>> though we can start with 2 and see how that goes. > >>> > >>> > >>> On Tue, Dec 10, 2013 at 2:36 PM, Dave Brondsema > >>> <[email protected](mailto: > [email protected])> wrote: > >>> > >>>> How frequently do we want to make Allura releases? Particularly when > do > >>>> we want > >>>> to make our next one - but we can talk in general terms too. > >>>> > >>>> I am thinking we should do one fairly soon. It took a while to get our > >>>> first > >>>> release out, but we now have a release script which should help > automate a > >>>> lot > >>>> and ensure we cover all the technical aspects. And I think we'll be > able > >>>> to get > >>>> the votes more easily now that we've gotten past the hurdle of the > first > >>>> one. > >>>> Also, the Incubator PMC (IPMC) has voted & invited me to join the > IPMC a > >>>> little > >>>> while ago, so I can cast a binding vote too. > >>>> > >>>> In general, I'd suggest we make releases after certain significant > >>>> features are > >>>> done, or after a few months if we're doing many small/medium changes > but > >>>> nothing > >>>> too big. Lately we've done a lot of work around Google, Trac, and > Github > >>>> importers. IMO https://sourceforge.net/p/allura/tickets/6922/ is a > >>>> blocker for > >>>> github, but after that is fixed might be a good time to release. > Another > >>>> big > >>>> ongoing initiative is activity streams, which might make a good 3rd > >>>> release). > >>>> > >>>> -- > >>>> Dave Brondsema : [email protected] (mailto:[email protected]) > >>>> http://www.brondsema.net : personal > >>>> http://www.splike.com : programming > >>>> <>< > >>>> > >>> > >>> > >> > >> > >> > >> > >> -- > >> Dave Brondsema : [email protected] (mailto:[email protected]) > >> http://www.brondsema.net : personal > >> http://www.splike.com : programming > >> <>< > >> > >> > > > > > > > > > > -- > Dave Brondsema : [email protected] > http://www.brondsema.net : personal > http://www.splike.com : programming > <>< >
