Strategy for Contributing Contents

[tajmone]

• Rename branch beta7-prep-contributing → dev-contributing.
• Rebase dev-contributing on master.
• Update CONTRIBUTING.md to embody the new branches strategy (see discussion below).
• Update manual/CONTRIBUTING.md to describe the new branches naming conventions and development and release strategies for official Manual release and Alpha dev/previews (see discussion below).

Currently working on the following documents on branch dev-contributing:

• CONTRIBUTING.md
• manual/CONTRIBUTING.md

---

See also:

• CONTRIBUTING.md (on master branch)
• Issue #59 — discussion on ALAN Manual branches strategy for Beta vs Alpha.
• Issue #71 — considerations on branching, merging/squashing, and committing strategies .

---

Ciao @thoni56,

I wanted to ask you about the way new contents should be proposed for the Manual (and any other doc in general). If it's OK with you, I was thinking that new content should be proposed in separate branches (created ad hoc for each new content submission), so there is a chance for you (or whoever will be appointed to supervise the documentation project) to discuss, revise, edit and approve (or reject) new contents.

Unlike fixing of typos and other minor changes, new contents are a bit of a delicate matter, and I think their addition should be supervised. This branch-based approach, on the other hand, allows freedom to anyone to at least propose contents vi pull requests. As for those with full access to the repository (like me), it boils down to separating what is editing work and contents changes.

For example, I feel I could write some contents on the internationalization/localization of Alan, since I'm fresh from the library translation, but I'd prefer to work on a separate branch where there is space to discuss and revise all the proposed contents before merging them.

What do you think about this?

[thoni56]

I think this is an excellent approach. I've always thought branches was the "theoretically" correct choice, but often found that working directly on the master is less of a hazzle.

The division that you propose, sounds a natural combination. So let's go with that. Would you mind adding a line or two about that in the Readme, so that we remember it ;-)

[tajmone]

Would you mind adding a line or two about that in the Readme, so that we remember it ;-)

I will, definitely!

I'm also thinking of starting to use the Wiki as a "public notebook" to gather useful links, tips, and guidelines about editing and converting the documentation via AsciiDoc.

[tajmone]

I've created a first draft document on Contribution Guidelines:

• https://github.com/alan-if/alan-docs/blob/master/CONTRIBUTING.md

It will get polished in time, but it should do for a start.

[tajmone]

Nightly vs Upcoming Beta

During our work on the Alan Manual I've come to realize that in the future we should adopt a dual strategy for its development:

• Nightly Releases — contents updates relating to current official Alan Beta.
• Upcoming Beta — contents updates pertaining the next Beta release (i.e. concerning features currently available only in Alpha dev snapshots).

The idea matured from the awareness that between each Beta release there's a rather lenghty time lapse, so me might want users to enjoy contents updates on nighlty releases without having to wait for the next Beta (which could take anything from 6 moths to a year).

This could be approached by using two different dev branches:

• dev-manual for nightly releases preparatory work.
• dev-manual-alpha for upcoming Beta releases preparatory work.

A Nightly Releases would be any version of the Manual which is merged into master branch — referred to as "nightly" because it's slighter up to date in respect to the version bundled with the various SDK zip files downloadable from the website.

In practical terms, we would work on branch dev-manual for all contents updates that are not specific to upcoming new features, and once in a while merge into master when there's a polished update ready for integration.

As for new features, these would be added on the dev-manual-alpha branch, to keep them separate from the Manual referring to the current Alan version. This dev branch should be rebased on dev-manual as often as possible, in order to keep it in synch with the base doc and avoid later merge conflicts.

This approach also simplifies the workflow for we have fixed branches name (as opposed to Beta7, Beta8, etc.). As usual, specific topics can be worked on in sub-branches like dev-manual-AppG, dev-manual-somefeature, dev-manual-alpha-newfeat, etc., which would then be merged in their respective base branches once ready and reviewed.

Do you think it makes sense? Any advise and better ideas?

[thoni56]

I think this is an excellent idea and strategy, leveraging the "normal" feature branch and release concept onto documentation! Great benefit of having a text-based format as the source.

So in principle documentation of new features are introduced in the dev-manual-alpha branch and evolving, adding and improving descriptions of things that's already in should go in dev-manual.

[thoni56]

Given the discussion in #59 we have now ameded this thinking a bit. Still a dual strategy, but more clearly:

• master follows the official releases (which at this point is 3.0beta7)
• dev-man branch which should follow the continuous snapshots

This means that documentation should as much as possible be updated for each feature or change that is made to the SDK, but also layout and tooling changes happen on the dev-man branch. (Perhaps after being tried out on a completely different branch, of course.)

This also means that documentation work means local merging/re-basing as with source code.

So, should we close this issue then? Probably ensure that CONTRIBUTION does not contradict this first. (CONTRIBUTION primarily addressing "external" contributions, I guess.)

[tajmone]

Agreed then.

So, should we close this issue then?
Probably ensure that CONTRIBUTION does not contradict this first. (CONTRIBUTION primarily addressing "external" contributions, I guess.)

Yes, I was actually working on the CONTRIBUTING.md doc locally, I'll rebase it and polish it as required. Then I'll close the issue.

[tajmone]

Renamed beta7-prep to dev-man!

Ok @thoni56, I've now renamed beta7-prep to dev-man, and deleted the old merged PR branches.

DON'T FORGE TO UPDATE YOUR LOCAL CLONE!

Bare in mind that the preview links in some Issues won't work anymore due to the branch renaming; but I'll try to edit all the links that I came across.

[tajmone]

Ok @thoni56, I've fixed the CONTRIBUTING docs (the existing one and the new one). They're ready to merge on master, but I'd like you to look at them before merging, just in case I left out something or they contain mistakes.

[tajmone]

Merged into master and deleted branch