Introduce "Feature branches" workflow to our API specs

[wrygiel]

Currently, @kaiqu's strategy is to put all proposals into example files. This strategy is perfectly okay at this point (because almost everything is a "draft proposal"). However, as we progress, we will need a way to:

• Clearly separate "more stable features" from "draft proposals".
• Propose two (or more) conflicting solutions for a single problem.
• Keep XSDs and XML examples in sync, for each of those proposals.

In Git, this problem is usually solved with feature branches. In short, we will need to:

• Move all disputable proposals to separate feature-branches to avoid confusion on the master branch (and, similarly, stable-* branches later on).
• Keep the master "clean". It will contain only those features which we are reasonably sure we need. These features will still change in a backward-incompatible way, but they won't change "much" (e.g. the elements may get moved or renamed, but their structure and meaning will probably remain unchanged).
• The stable-v1 branches will need to always be clean, and contain only the accepted features. However, we won't rush with introducing stable-* branches. We will wait a couple of months and test all features on master first.

You can already see two examples of such feature-branches in the Developers' page, in Institutions API chapter. Screenshot below:

If there won't be any objections, then I will begin to introduce this strategy to all other APIs, after I return from my holidays in December.

[kaiqu]

If there won't be any objections, then I will begin to introduce this strategy to all other APIs,

Sounds good to me.

after I return from my holidays in December.

Speaking of that - when do you leave, and who will take over the XSDs while you're gone?

[janinamincer-daszkiewicz]

Speaking of that - when do you leave, and who will take over the XSDs while you're gone?

Answering on Wojtek's behalf - Wojtek leaves early morning on Friday November 4th. XSD will have to wait for his return. More info will come in an email Wojtek will send tomorrow.