This is the primer on using git and translating.
When they are ready, contents for this wiki end up on devuan.org for perusal by the many people who visit there and need information on getting setup.
Pages to translate
Choose from the following pages. Frozen pages are less work to translate and maintain, active pages are much more prone to changes and if you choose to translate them you will need to change them often to keep up with the latest changes.
- General information
- Migrate to Jessie
- Migrate with minimalism
- Jessie minimal install
- Upgrade to ASCII
- Devuan without D-Bus
- Minimal xorg install
- Minimal XFCE install
- Openbox guide
In every case you should credit yourself on the page you translated. For example:
Translation by your name
At the top or near the bottom of each page.
This should be enough to comply with CC by SA, and others will be able to copy your work with cloning from git if they wish to.
I strongly encourage collaboration, especially in git where that is easy to do. In that case, you should also include anyone else who worked on that document.
Translation by your name with improvements by their name
If you're working with git you will need to use commit messages to make your changes clear as well. This will be explained below.
We will focus first on creating the branch for your language. We will then talk about going about the translation work with git.
Create a git account on git.devuan.org and see the guidance on setting up your keys here and then again here . If you're unable to get past this step don't panic, you will be able to use https instead provided you enter your username and password each time. If you do get your keys setup you will not have to do that when commiting your changes.
First clone the repository.
git clone email@example.com:dev1fanboy/Upgrade-Install-Devuan.git
Or if you could not setup your keys for some reason use the https version.
git clone https://git.devuan.org/dev1fanboy/Upgrade-Install-Devuan.git
Every branch should use a
two letter language code
hereafter known as
We can use one command to create a branch and switch to it immediately.
git checkout -b lc
Then make the directory to work with.
Copy the file(s) you wish to work with into the directory you just created, leaving the name intact.
cp filename.md cl/
Now you have those files copied, do not start work on them yet as it's helpful to first push your branch to gitlab.
Add the new files to the list of changes that git will push back to the repository.
git add *
Now commit your changes using git-commit. The repository will not be written to yet.
git commit -a
Enter a commit message. It could be something like:
Created the es branch for Spanish translation.
Now push your changes to setup the branch on gitlab.
That's it, your branch will be created. If you didn't setup your keys you will be asked to provide your login information.
Now you can start translating.
Use your favourite editor to work on the page you want to translate.
When you are done repeat the process as above.
git add lc/*
git commit -a
That's it, translation has been submitted.
You should regularly update your branches against master, especially just before you start translating pages as they may have been updated.
First checkout the master branch.
git checkout master
Then update it against the remote branch.
Then switch back to the branch you're working on.
git checkout lc
Then update it against the master branch.
git rebase master
Finally push back your changes.
Working with markdown
There are many resources available for working with markdown out there, particularly you want those that refer to git or GFM (git flavour markdown).
When you are done translating a page or set of pages, you can merge to the development branch which will in turn be merged with master regularly.
Merge requests can be made by looking at the branches then making a merge request against the branch you want, development in this case.
[EDIT] I add below the complete sequence of the above commands and the issues I faced. The el branch was existing (initially created through the web interface) and contained some translated files already. This is the use case, when a new translator joins the effort and tries to clone the branch to work on it.
git clone firstname.lastname@example.org:dev1fanboy/Upgrade-Install-Devuan.git
This creates directory Upgrade-Install-Devuan. One has to change into this directory to run further git commands.
git checkout -b el mkdir el
I then copied several files from master into el branch that were not existing there.
cp <missing-files>.md el/
git add * git commit -a [el ab2e915] Add new files to be translated to Greek 10 files changed, 1033 insertions(+) create mode 100644 el/dbus-free-software.md create mode 100644 el/debloating-recommends.md create mode 100644 el/devuan-without-dbus.md create mode 100644 el/jessie-install.md create mode 100644 el/jessie-minimal-install.md create mode 100644 el/migrate-jessie-minimalism.md create mode 100644 el/migrate-to-ascii.md create mode 100644 el/minimal-xfce-install.md create mode 100644 el/openbox-guide.md create mode 100644 el/upgrade-to-ascii.md git push fatal: The current branch el has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin el To git.devuan.org:dev1fanboy/Upgrade-Install-Devuan.git ! [rejected] el -> el (non-fast-forward) error: failed to push some refs to 'email@example.com:dev1fanboy/Upgrade-Install-Devuan.git' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details. git pull There is no tracking information for the current branch. Please specify which branch you want to merge with. See git-pull(1) for details. git pull <remote> <branch> If you wish to set tracking information for this branch you can do so with: git branch --set-upstream-to=origin/<branch> el git pull firstname.lastname@example.org:dev1fanboy/Upgrade-Install-Devuan.git el From git.devuan.org:dev1fanboy/Upgrade-Install-Devuan * branch el -> FETCH_HEAD Merge made by the 'recursive' strategy. chroot-install-environment.md | 4 +- el/.gitkeep | 0 el/README.md | 43 +++++++++++++++++ el/chroot-install-environment.md | 67 ++++++++++++++++++++++++++ el/full-disk-encryption.md | 76 +++++++++++++++++++++++++++++ el/general-information.md | 100 +++++++++++++++++++++++++++++++++++++++ el/migrate-to-jessie.md | 78 ++++++++++++++++++++++++++++++ el/minimal-xorg-install.md | 94 ++++++++++++++++++++++++++++++++++++ el/network-configuration.md | 64 +++++++++++++++++++++++++ network-configuration.md | 8 +++- 10 files changed, 531 insertions(+), 3 deletions(-) create mode 100644 el/.gitkeep create mode 100644 el/README.md create mode 100644 el/chroot-install-environment.md create mode 100644 el/full-disk-encryption.md create mode 100644 el/general-information.md create mode 100644 el/migrate-to-jessie.md create mode 100644 el/minimal-xorg-install.md create mode 100644 el/network-configuration.md
Is there something wrong on my side or the page instructions need editing?
Otherwise, the guide is good for quick on-boarding translators. Perhaps, each language could append a section with language specific instructions.
I think we do need to distinguish between starting a new language translation setup and contributing to an existing one.Edited by Menelaos Maglis
I think you possibly went in the wrong order there. It should be:
git checkout master
git checkout el (standing in for lc)
git rebase master (this will sync your branch with master, note the need to pull it first as above)
then git push
In any case, I will look soon and update all branches, and add anything that's missing.
I'm using (instead of rebase):
git checkout master git pull git checkout es git merge master es git push origin es
To keep "es" updated with "master".
I didn't have any problem with that but, is this workflow right or wrong? What is the difference between rebase and merge?
I didn't credit myself on the pages I've translated, and being a requisite to comply with the license, I will do it next.
Question is: the phrase "Translation by xxxx" should be in English or in the target language (i.e. "Traducido por xxxx")?
@linuxito it should be OK to put it as "Traducido por.." and that should cover you for all changes, it's just that git will automate that with commit messages as well.
It is OK to merge master into your working branch as well, it should have the same result. As far as workflow, we can just do either as it's not a requirement (note that we are not working directly on a devuan.org branch).
@mmaglis Since your branch already exists you can use "git checkout el" instead. The -b flag will cause the branch to be created when it's not there. So in this case you don't need the -b flag. Use 'git branch' to see all branches. I will add this when updating the guide.
When I catch up in the master branch I'll create this guide in contributing.md instead as people familiar with git may look for that.
I'm not being able to checkout to the pt branch.
EDIT: Nevermind, after some searching I've found the proper way of doing this:
git checkout -b pt origin/pt
* master remotes/origin/HEAD -> origin/master remotes/origin/de remotes/origin/development remotes/origin/el remotes/origin/es remotes/origin/it remotes/origin/it-in-folder remotes/origin/it-updated remotes/origin/master remotes/origin/pl remotes/origin/pt
cdinto Upgrade-Install-Devuan/pt and run git checkout pt, but it returns
error: pathspec 'pt' did not match any file(s) known to git.
git checkout ptfrom Upgrade-Install-Devuan instead. It prints nothing back to me;
git branch -ashows that I'm still on master. How do you do it?
I keep changing my operating system all the time. This time I decided to try Trisquel, and now I got stuck here. Trisquel 8 is based on Ubuntu 16.04. Perhaps this old version of git works differently.Edited by Douglas
Sorry for the delay getting back to you.
You should really run git checkout pt in the Upgrade-Install-Devuan directory, since git keeps that information in the root (parent) directory.
I checked myself and found the situation is the same. Your edit with the solution worked to fix that issue. I don't remember having to do this but apparently it's how to do it now.