1. Work Branch
2. Translation Checklist
3. Submit Pull Request
4. Pull Your Changes

which branch to use for individual translator's work, which branch to merge into, and which branch is for final work, what criteria must be met before it's ready to sumbit to official repository, etc.

You need to pick up a branch as your workspace. If you clone from my CakePHP docs fork, you can use the branch zh_work for this purpose. Since this branch contains all the previous translation work not submitted yet, you will not miss any work already done. Otherwise you can create you feature branch and take the relevant translated files from my zh_work branch as the basis to start with.

Switch to the branch you choose and start your translation work. Remember to read the Documentation and ensure you know all the sphinx syntax used for this cookbook.

All the Simplified Chinese of the cookbook is in the /zh/ folder, so your translation work should be put in this folder. However the language code we use for Simplified Chinese is zh_CN. All these are already set up in the sphinx configuration and build scripts and you do not need to worry about it.

After you finish some translation work and are ready to submit it, make sure your work meets the necessary criteria.

If you are translating a file that has not been translated before, you need to finish the translation of the whole file before you can submit it. Please read the checklist and ensure you know the criteria for a complete translation.

If you are improving the existing translation, make sure you follow the same checklist.

After you are satisfied with your translation work, you can commit it with a meaningful commit message. Usually we prefix a language code in the message. So a commit message for Simplified Chinese could be [zh_CN] done /zh/models.rst. Do remember to use standard communication language, English, in all the commit messages as the project maintainers will not recognize Chinese.

After checking against the checklist, follow the steps below prepare and submit your work in a pull request.

First you need to get the latest changes from official docs project. Switch to your master branch and pull from the upstream/master remote.

Now choose a feature branch to hold your work for the pull request. Usually you will start your translation work in a feature branch but it does not work for this translation project since there are existing translation work in zh_work branch that is not submitted yet.

Next, if you start your translation work in a feature branch, you do not need to do anything. But if you start with my zh_work branch, please create the feature branch for the pull request from the updated master branch. Usually I will use the cleaned zh branch for this purpose and merge from the master branch.

Now you are in the feature branch. Use cherry pick described in Integrating Contributed Work or manual merge or whatever method to merge only your work (without any other changes) into this branch. This is different from normal git workflow where the work starts from the feature branch. But the normal merge does not work here since the zh_work branch contains unfinished translation work that you do not want to submit. So you have to start from the half done work in zh_work branch.

Next push both your master branch and your feature branch (or zh branch if you are using my fork) to the origin remote.

Then visit the fork on the Github using a browser. For example, mine is https://github.com/blackpuppy/docs. Go to the branch view and click the New pull request button besides the specific feature branch (mine is zh branch). A new pull request creation page is shown with the changes between the feature branch and the master branch on this fork. That is why earlier you need to update both the master branch and the feature branch from the official docs project and push them to the fork repository.

After reviewing and confirming the changes are what you want to submit, click the Create pull request button. A new pull request has been created and will wait for the project maintainers to approve and merge. If the maintainers think your work needs some correction or improvement they may ask you to make further changes. You can just make the changes in the feature branch and push it to the fork repository. The further changes will be included in the the same pull request before it is merged by the maintainers.

Once your pull request is merged by the project maintainers, a build will be started automatically. You can check the status of the build on CakePHP CI. After the build is finished successfully, you can see your translation work at the official cookbook.

After your work is merged into the official docs project, your translation work becomes part of official docs project. You can pull it back from the official CakePHP docs project into the master branch and merge it into other branches (zh_work branch and oschina branch). Next push these branches to the corresponding remotes such as origin/zh_work, origin/oschina and oschina/master so that your team can get the latest updates.