Publishing

When a user is ready to publish their target translation they must complete several steps.

Chunk Validation

In this step the user is presented with a list of incomplete chunks. Clicking on one of these chunks will take the user back into the review mode where they can inspect the chunk in question.

Incomplete Chunks

Users are not required to complete all chunks in order to proceed with publishing however they will have to scroll all the way down to the bottom of the list in order to find the "next" button. This is purposely intended to cumbersome in order to deter users from publishing incomplete Target Translations.

Merge Conflicts

Users are required to resolve all merge conflicts before proceeding with publishing. If the app detects that a chunk contains a merge conflict (it will contain the merge conflict code added by git) that chunk will be flagged as containing a conflict and the user will not be allowed to proceed to the next step even if they scroll all the way down to click on the "next" button.

For more details about merge conflicts see Importing a Target Translation#merge-conflicts.

Add Contributors

In this step the user will have the opportunity to add additional contributors to the Target Translation. The full_name of the current profile will be automatically added as a contributor to the Target Translation. Contributors may be added, edited, or removed during this step.

Review Legal Documents

In this step the user will be able to review some details about their Target Translations such as name, language etc. in addition to the Terms of Use, Translation Guidelines, Statement of Faith, etc.

Publish

In this step the user will have the option to upload their Target Translation to Door43 or to export it in a number of different human readable formats.

Uploading is a little more tricky because it is possible there are changes on the server that are not present on the user's device. The app must be able to handle merge conflicts found by pulling down changes from the server and allow the user to handle them appropriately before continuing to upload. Follow the below steps in order when performing an upload

1. Create a new branch backup-master (replace if it already exists)
2. Pull down changes from the server into master. This will also indicate if we are not authenticated or the repository does not exist
3. Register SSH keys if authentication failed
4. Create repository if it does not exist
5. If there were no merge conflicts then tag the Target Translation and push to the server
6. If there were merge conflicts then:
7. revert any conflicts that may have occurred in manifest.json
8. request user intervention

NOTE: we revert conflicts in the manifest to avoid corruption if the publish is aborted in an unusual manner. The correct version of the manifest.json will be retrieved during user intervention.

Merge Conflicts

When a merge conflict occurs after pulling down changes from the server the user should be presented with the following options:

• Review Conflicts - this aborts the entire publishing workflow and take them back to the review mode where they can view the merge conflicts
• Keep Server Changes - this will favor the changes on the server and handle the merge conflicts automatically before continuing to tag and push to the server
• Keep Local Changes - this will favor the user's local changes and handle the merge conflicts automatically before continuing to tag and push to the server
• Cancel - this will roll back the merge that resulted from the pull request and return them to the publishing step (they may still want to use one of the other publishing methods).

In every option above except for "Review Conflicts" the master branch will need a hard reset from the backup-master branch. This rolls back the changes made during the pull request.

git reset --hard backup-master

If the chosen option provides a merge strategy we will restart the publish starting with creating the backup branch as shown above in the Publish section. However, this time we will provide the pull request with the selected merge strategy so that git knows who's changes to keep: theirs (the server), or ours (local changes).

The manifest.json will need to be merged manually according to rules outlined in Importing a Target Translation for merging two target translations. You'll need a version of the manifest from the server as well as locally.

Tagging Target Translations

When a Target Translation is ready to be uploaded a new annotated tag should be added to the repo titled in the following format:

R2P/yyyy-MM-dd/HH.mm.ss

With the annotation:

Request to publish: [target translation id] by [gogs user name]

The tag above should be added before being pushed to the server. If HEAD has already been tagged as published do not create a new tag. The date should be set using the UTC time zone.

NOTE: you must manually push the tags to the server separate from pushing the code. e.g. git push origin --tags

Online Backups

For details about backups see Backups.