Re: Lets move forward

Hi Markus

First of all, I never received the email Asbjorn responded to. Weird. Any ideas?

December 15 2016 9:43 PM, "Asbjørn Ulsberg" <asbjorn@ulsberg.no> wrote: 
> 2016-12-11 20:49 GMT+01:00 Markus Lanthaler <markus.lanthaler@gmx.net>:
> 
>> In the coming months we will experiment with using GitHub as our main
>> development platform.
> 
> Excellent!
> 
>> The official specification [2] will **not** be kept up to date as that results in
>> too much friction.
> 
> Is it not possible to host the specification on a GitHub Page? That
> allows us to write the entire specification in Markdown, which I
> believe would be highly beneficial to our productivity.

The Open API Specification has an open issue with proposals for authoring tool [1]. One proposal is Bikeshed (see example in the issue). It looks quite nice, has a friendlier syntax (than palin HTML) and produces W3 styled specification.

However I see that ReSpec also supports Markdown, alas only not for included files [4].

And regarding hosting, I think that any stable state should be available where it is now (hydra-cg.com) and we can use GitHub pages to always have the draft available. See my fork [2] hosted by GitHub [3].

> 
>> Instead, I created a drafts folder in our repository [3] and seeded it with
>> some content. My hope is that this eases collaboration and speed up
>> progress.

I'm not against but please help me understand how it will help.

>> I would like to keep our discussions in the coming months concreter than
>> they have been in the past. I created a (still almost empty) document [4]
>> describing the interface of a yet-to-be-built client interface. I hope we
>> will complement this with running code shortly which will hopefully help us
>> to stay even more focused.
> 
> Yes, that would be great!
> 
>> Spec-wise, I do expect that most contributions from now onwards will be made
>> in the form of pull requests. We will then discuss them directly on GitHub.
> 
> Does this mean my assumption of working on smaller, more focused parts
> of the spec, wrong?
> 
>> As soon as we reach consensus, I'll merge them.
> 

So, will we work on the drafts on main spec? I'm inclined to think that pull requests themselves can be viewed as drafts. When someone creates a pull request to the main spec, others can view it the changes and big picture on the fork. 

Hence, I'm skeptical towards the drafts folder. If anything else, git branches can be used for completely new features (such as sketching out the client interface).

> 
>> For me personally, the highest priority is still to get collections done as
>> they are such a fundamental building block in almost every Web API. But I'll
>> wait with pushing that forward till we have Rubens first version as I don't
>> really know what he has in mind and it might change things more
>> fundamentally.
> 
> Agreed.
> 

I too agree. Basic paging and filtering is a must. We can work on more advanced scenarios once we have the groundwork done.

[1]: https://github.com/OAI/OpenAPI-Specification/issues/829
[2]: https://github.com/tpluscode/Hydra
[3]: http://t-code.pl/Hydra/spec/latest/core/
[4]: https://github.com/tpluscode/Hydra/blob/master/spec/latest/core/index.html#L169

Received on Friday, 16 December 2016 12:42:16 UTC