[Cuis] Managing the evolution of Cuis (Public APIs, checking them and Releases)

[Phil (list)]

On Thu, 2015-07-23 at 11:59 -0300, Juan Vuletich wrote:
> Hi Folks,
> 
> I've just re-read the very rich threads related to this. Thank you all 
> for thoughtful and valuable considerations and opinions. This mail 
> attempts to make really small summary, to start taking action.

My quick summary to your previous replies: I agree!  :-)

> 
> First, the easiest. Releases
> -------------------------------------
> Several of you see real value on doing a few named releases per year. 
> Theres' no big downside, so, let's do it. I think this is a good time to 
> do a release. So, I'll refrain to introduce any major changes, except 
> important bugfixes. Please start testing / updating / fixing your 
> packages and applications. When we are all happy, and we all agree that 
> the whole ecosystem is in a healthy state, we'll call that a release.
> 
> We need a name for this release. The obvious choice is "Cuis4.3-nnnn". 
> So, there might be a Cuis4.3-2456, and as that branch evolves, a 
> Cuis4.3-2457 and Cuis4.3-2458. Shortly after, we'll be doing the "alpha" 
> updates of Cuis4.4. So, I guess #2459 would be (a potential risky 
> change) for Cuis 4.4. What if later we need to apply some patch to the 
> stable Cuis4.3? How would we name it?
> 

My .02 on how we might manage the different branches is in my latest
reply to Hannes.  If you're happy with the way you're managing Morphic
3, why not start with that approach?  Or you could use two git branches
and periodically merge fixes from stable into development while you're
working on it, then merge development back into stable for release... or
something like that.  I'll defer to what you think will work best for
your workflow here...

> After a bit of discussion, I can take action. Or you can volunteer for 
> Release Manager or member of the Release Team for Cuis 4.3.
> 

Consider me volunteered.  I'll be happy to help in whatever way I can...
how can I best do that?  

> Next, Documented, Public APIs
> -------------------------------------------
> 
> Use pragmas, like PubicAPI (some method we intend to support and keep in 
> that hierarchy), or CalledFromOutside (some method our yet-to-be-written 
> tool detects as called from another package). Write tools for analyzing 
> them. Do not remove them without due discussion.
> 
> It should be possible to write tests for existence of APIs.
> 
> This area is new to us, and we'll learn as we go.
> 

Yep.  Undiscovered Country and it will likely take a few iterations to
get to what makes sense.

> Anybody can take action here. Documenting APIs by hand, writing tools to 
> try to autogenerate them, writing tests that check for existence of 
> specific APIs, whatever you can come up with.
> 
> This sounds like a major strategic direction, and in a very early stage, 
> so maybe we'd not include anything of this in the Cuis4.3 release, but 
> make this the start of the Cuis4.4 effort.
> 

Agreed.  Besides, I don't think we'll have even version 1 of APIs ready
for 4.3. (because the stable API stuff will likely still be, umm...
unstable)

> Thoughts? Or feel free to start coding!
> 
> Cheers,
> Juan Vuletich
> 
> _______________________________________________
> Cuis mailing list
> Cuis at jvuletich.org
> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org