-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Strategy for Contributing Contents #6
Comments
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 ;-) |
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. |
I've created a first draft document on Contribution Guidelines: It will get polished in time, but it should do for a start. |
Nightly vs Upcoming BetaDuring our work on the Alan Manual I've come to realize that in the future we should adopt a dual strategy for its development:
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:
A Nightly Releases would be any version of the Manual which is merged into In practical terms, we would work on branch As for new features, these would be added on the This approach also simplifies the workflow for we have fixed branches name (as opposed to Do you think it makes sense? Any advise and better ideas? |
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 |
Add new `manual/CONTRIBUTING.md` for guideline on the Git development for the Alan Manual, and the strategies for keeping separated work on the Manual for the current Alan version from work on new features due with the next upcoming relase (i.e. "nighlty" vs "alpha"). For more info: See #6.
Given the discussion in #59 we have now ameded this thinking a bit. Still a dual strategy, but more clearly:
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.) |
Agreed then.
Yes, I was actually working on the |
Renamed
|
Add new `manual/CONTRIBUTING.md` for guideline on the Git development for the Alan Manual, and the strategies for keeping separated work on the Manual for the current Alan version from work on new features due with the next upcoming relase (i.e. "nighlty" vs "alpha"). For more info: See #6.
Edit the text of `manual/CONTRIBUTING.md` so mirror the new development strategy and branches naming conventions. (See #6)
Revise and improve contents of `CONTRIBUTING.md`, exposing the general contributors' guidelines (See #6): * Split paragraphs one-line-per-sentence. * Provide general guidelines on usage of development branches for each document, their naming conventions, and merge and PR strategies. * Add guidelines on adding a Glossary to new documents.
Ok @thoni56, I've fixed the CONTRIBUTING docs (the existing one and the new one). They're ready to merge on |
Merged into
|
beta7-prep-contributing
→dev-contributing
.dev-contributing
onmaster
.CONTRIBUTING.md
to embody the new branches strategy (see discussion below).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
(onmaster
branch)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?
The text was updated successfully, but these errors were encountered: