Difference between revisions of "A Translators Guide to Git"

From Gramps
Jump to: navigation, search
(Creating a pull request)
(Configuration of Git)
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Configuration =
+
Git is a distributed control version system, and it is widely used for maintaining source code in opensource software projects like Gramps. Git can track changes to any text file (not only source code), so may be used also to maintain text-based translation files.
  
Git includes your name and email address in commits. To configure them, use the following commands:  
+
Thanks for your interest in helping translate Gramps.
 +
 
 +
= Install Git =
 +
Download and install Git for your operating system from:
 +
 
 +
https://git-scm.com/downloads
 +
 
 +
= Configuration of Git =
 +
 
 +
You will need to Configure Git so that Git includes your name and email address in the Git messages known as ''commits''.
 +
 
 +
To configure them, use the following commands:  
 
  git config --global user.name "John Smith"
 
  git config --global user.name "John Smith"
 
  git config --global user.email [email protected]
 
  git config --global user.email [email protected]
Line 24: Line 35:
 
To create a local branch which tracks a branch on the server, use:
 
To create a local branch which tracks a branch on the server, use:
  
  git checkout -b gramps50 origin/maintenance/gramps50
+
  git checkout -b gramps51 origin/maintenance/gramps51
  
 
= Updating a translation =
 
= Updating a translation =
  
There are two main workflows.  The basic workflow is simpler, but is only available to developers that have write access to the repository.  Otherwise translators should create a pull request. This may also be preferred by translators who are new to Git and would their contribution checked before it is pushed to the repository.
+
There are two main workflows.  The recommend one is that translators should create a pull request, for those translators new to Git and this will allow their contribution to be checked before it is pushed to the repository. The other is the simple workflow for developers, but is only available to developers that have write access to the repository, otherwise please create a pull request.
 +
 
 +
== Creating a pull request ==
 +
 
 +
You first need to make a copy of the Gramps repository in GitHub this is referred to as creating a Fork.  To do this, go to the Gramps repository page,
 +
 
 +
https://github.com/gramps-project/gramps
  
== Basic workflow ==
+
then login, and click on the "Fork" button.
 +
 
 +
Create a remote to access your Fork:
 +
 
 +
git remote add myfork [email protected]:''<username>''/gramps.git
 +
 
 +
where ''<username>'' is you GitHub username.
 +
 
 +
Create a branch to work in:
 +
 
 +
git checkout -b xx gramps51
 +
 
 +
Now edit the po file using your favorite method and once complete.
 +
 
 +
Commit your changes:
 +
git add po/xx.po
 +
git commit -m 'Update xx translation'
 +
 
 +
You can update the ''gramps51'' branch at any time.
 +
 
 +
git checkout gramps51
 +
git pull
 +
 
 +
You rebase your working branch on the ''gramps51'' branch at any time.
 +
 
 +
git checkout xx
 +
git rebase gramps51
 +
 
 +
When you are ready to make a pull request, push your translation to your fork:
 +
git push myfork xx
 +
 
 +
Now create a pull request within GitHub.
 +
 
 +
If you have recently pushed a branch to your fork, then GitHub will highlight this when you visit the repository page, and give you an option to create a pull request.  Otherwise click on the "New pull request" button.
 +
 
 +
Make sure that you select "gramps51" as the base branch.
 +
 
 +
== Simple workflow for developers ==
 +
 
 +
This simple workflow is for developers, that have write access to the repository, otherwise please create a pull request.
  
 
Checkout the maintenance branch:
 
Checkout the maintenance branch:
  git checkout gramps50
+
  git checkout gramps51
  
 
Get the latest changes:
 
Get the latest changes:
Line 65: Line 121:
 
When you are completely happy, push the changes to the server.  If in doubt, don't.
 
When you are completely happy, push the changes to the server.  If in doubt, don't.
  
== Creating a pull request ==
+
==See also==
 
+
* [[Portal:Translators]]
Fork the Gramps repository in GitHub.  To do this, go to the gramps repository page,
+
* [[Translating Gramps]]
 
 
https://github.com/gramps-project/gramps
 
 
 
then login, and click on the "Fork" button.
 
 
 
Create a remote to access you fork:
 
 
 
git remote add myfork [email protected]:''<username>''/gramps.git
 
 
 
where ''<username>'' is you GitHub username.
 
 
 
Create a branch to work in:
 
 
 
git checkout -b xx gramps50
 
  
Now edit the po file.
+
[[Category:Translators/Categories]]
 
+
[[Category:Community/General]]
Commit your changes:
 
git add po/xx.po
 
git commit -m 'Update xx translation'
 
 
 
You can update the ''gramps50'' branch at any time.
 
 
 
git checkout gramps50
 
git pull
 
 
 
You rebase your working branch on the ''gramps50'' branch at any time.
 
 
 
git checkout xx
 
git rebase gramps50
 
 
 
When you are ready to make a pull request, push your translation to your fork:
 
git push myfork xx
 
 
 
Now create a pull request within GitHub.
 

Revision as of 04:26, 23 September 2020

Git is a distributed control version system, and it is widely used for maintaining source code in opensource software projects like Gramps. Git can track changes to any text file (not only source code), so may be used also to maintain text-based translation files.

Thanks for your interest in helping translate Gramps.

Install Git

Download and install Git for your operating system from:

https://git-scm.com/downloads

Configuration of Git

You will need to Configure Git so that Git includes your name and email address in the Git messages known as commits.

To configure them, use the following commands:

git config --global user.name "John Smith"
git config --global user.email [email protected]

Git will automatically convert line endings for you. Use the following settings:

git config --global core.autocrlf true  # Windows
git config --global core.autocrlf input  # Linux/Mac

The following configuration option simplifies pushing a branch back to the server:

git config --global push.default upstream

Obtain a copy of the repository

Clone the repository:

git clone [email protected]:gramps-project/gramps.git Gramps

Change directory:

cd Gramps

Create a maintenance branch

To create a local branch which tracks a branch on the server, use:

git checkout -b gramps51 origin/maintenance/gramps51

Updating a translation

There are two main workflows. The recommend one is that translators should create a pull request, for those translators new to Git and this will allow their contribution to be checked before it is pushed to the repository. The other is the simple workflow for developers, but is only available to developers that have write access to the repository, otherwise please create a pull request.

Creating a pull request

You first need to make a copy of the Gramps repository in GitHub this is referred to as creating a Fork. To do this, go to the Gramps repository page,

https://github.com/gramps-project/gramps

then login, and click on the "Fork" button.

Create a remote to access your Fork:

git remote add myfork [email protected]:<username>/gramps.git

where <username> is you GitHub username.

Create a branch to work in:

git checkout -b xx gramps51

Now edit the po file using your favorite method and once complete.

Commit your changes:

git add po/xx.po
git commit -m 'Update xx translation'

You can update the gramps51 branch at any time.

git checkout gramps51
git pull

You rebase your working branch on the gramps51 branch at any time.

git checkout xx
git rebase gramps51

When you are ready to make a pull request, push your translation to your fork:

git push myfork xx

Now create a pull request within GitHub.

If you have recently pushed a branch to your fork, then GitHub will highlight this when you visit the repository page, and give you an option to create a pull request. Otherwise click on the "New pull request" button.

Make sure that you select "gramps51" as the base branch.

Simple workflow for developers

This simple workflow is for developers, that have write access to the repository, otherwise please create a pull request.

Checkout the maintenance branch:

git checkout gramps51

Get the latest changes:

git pull --rebase

Now edit the po file.

Check status and differences:

git status
git diff

Stage the file for commit:

git add po/xx.po

Commit the change:

git commit -m 'Update xx translation'

Get the latest changes again:

git pull --rebase

Always use the '--rebase' option.

Check the log:

git log

Check using a graphical tool:

gitk

Look for anything unusual such as merge commits.

When you are completely happy, push the changes to the server. If in doubt, don't.

See also