Update process

[symfony-fr]

Update process

[martinqt]

What about creating branches for the differents sections, update them separatly more and less as eng doc is updated and them merge all the branches at the same time into master fr.

Sorry for the short version, i'm on a cellphone

[gregquat]

Managing the english doc consists most of the time to accept and merge PR in the differents branches.
For us, unfortunately, we cannot merge automatically (the english PR) and all the job is made manually. I don't know how we can work faster, maybe you're right I don't know yet. I'm afraid what you propose brings more work to manage all of these branches in addition of integrating the changes.

[martinqt]

The idea was instead of creating a first/second/third part branches, branches that stay alive between updates for book, components, ... The idea is to PR changes against the sections branches (book,...). Once everyone is up to date, we merge all the sections branches into the main one. This allow to follow commit and prepare changes without publishing them to the main branche.

Not sure I'm really clear. If you want i can try to create a fake repo to try this workflow or any other one.

[martinqt]

I've created a test repo there (martinqt/symfony-docs-fr-workflow-test).

[gregquat]

I made a PR for the Quick Tour. To test correctly, you should also create a branch 2.1.
All the PR which must be made in all branches can be manage as you think (I also think now :). For specific version commits, I think we should not create a branch per section.
As 95% of commits are for master and 2.1 (and 2.0 but we do not care) it's important we can apply a PR on both master and 2.1. For specifics commits for 2.1, we'll a make a specific commit directly on 2.1 branch.

[martinqt]

So if i get it well, for master the system is ok and for version branches we just PR the corresponding branche? Sounds good to me. I've granted you for the repo

[greg0ire]

@martinqt: you asked for my insight, so here it is (could very well be completely stupid):
I think what you want is to be notified as soon as the english documentation interesting branches (2.1 and master) have new commits. When this is the case, you wish to edit each and every commit coming from the english documentation, because it is very likely that there will be something to change in it.
Makes me think about to things :

• you should have branches tracking the english documentation.
• you should always use git rebase -i and amend all commits one-by-one or not? or in your private clone?, then merge the resulting branch in symfony-docs-fr public branches. This should address the "manual merge" problem.

Maybe you need to ask this workflow question on one of the stackexchange sites (stack overflow maybe?), there are plenty of git masters there.

[martinqt]

Thanks @greg0ire.

I don't really understand. How an english branch would be useful in this repo? Tracking can be done by watching repo, am i right? And i don't understand the rebase thing. I'm new to git but it seems really complex to me for the job we need to do. So far i understood, rebase clean history but i don't see where it's needed.

The idea was to create branches not to have to wait the current big sync every two weeks. It would be easier for someone to just sync two commits, send it to a public "temporary" branch, so if someone else want to sync a commit he/she can. And let say three days before our sync, we say "nobody sync commit ahead of #aaaa and catch up all sections and merge it into the master/2.1 branches.

I put it there: https://github.com/martinqt/symfony-docs-fr-workflow-test/wiki/_pages

[greg0ire]

Well, technically, cloning the repository doesn't mean you have an english branch in it. I mean, the english files will be in your .git folders, but as files of the remote repository. Let's say I want to translate symfony-docs in klingon. I would clone the symfony-docs repository, and then translate all the files in klingon, and make a commit "Initial translation". I will have only one local branch in klingon, and the origin/master branch, which is in english, will be a remote branch : I do not reference it.

Now, when you say tracking can be done by watching repo, it still looks a bit manual to me: you will be looking at your github news stream and try not to miss a commit in origin/master. But I think you're right, rebase is not the right tool here, because it will let you edit your commits I think, when you would rather want the new commit that arrived on origin/master, which means using git merge. The problem is that if there is a new english file, no conflict will be created and could miss this fact. I don't know if there is a merge option that let's you edit each commit before merging it, no matter whether there is a conflict or not.

[martinqt]

Sorry and didn't understood you were talking about cloning the repo. But having the english doc as the master branch of fr repo doesn't sound really nice (or i still miss something).

The point of this new workflow is not to catch every commits but to allow contributor to update the doc without waiting the current big update process. For now, except from saying "i handle this file from now" you can't really help by translating a little part. I think they do a diff between the previous to be sure not to miss anything. But this workflow doesn't seems really friendly to me because you have to handle the file. So you can't say "i saw this new feature and i wanted to translate it". The answer will be "we do this kind of translate every two week and we basically only accept bug fix. However you can handle the file from now if you want". I think this affray contributors.

@gregquat after a little re-read i saw you said that PR should be able to be applied on multiple branches. If the contributor don't create multiple PR we can add .patch at the end of the url and extract a patch to be applied. But i think if we create a wiki page which explains how they should create the others PR and redirect them to this page when we need mutiple PR, it should do in most of the case.

[greg0ire]

You don't really have "the english doc as the master branch of fr repo", you would rather have "a french master branch tracking the english branch of the repo". The word tracking is key here, it is the main benefit of this method I think. But as you stated, you don't want to catch every commit, so I think this is pointless for your usage after all.

[martinqt]

I may finally got it. Indeed it might not be required. But thanks anyway.

[gregquat]

I'm very interested in a great process since I (and @skeud) have no time at this moment to update the doc. As @greg0ire said, we use a manually (and very loooong) process to check the update and translate them.
I'm not good enough with git to say if there is THE solution.

@martinqt, actually, you don't have to wait "the big update" to update the doc. But if you want to make PR and update the doc, you must start when I stopped the last time (see the wiki) and not forget a PR. That's why we don't accept "english update PR", it would be too hard to manage. But if the PR are made in the same order as the original ones in the english repo, it's probably possible.

[greg0ire]

I asked the question on SO : http://stackoverflow.com/questions/13747319/workflow-for-a-documentation-translation-repository
I hope it does not get closed, since it is not very related to programming

[gregquat]

No very good an acceptable solution was found. For the moment