many tutorials on the web for this
just the basics here
A way to go “back and forth in time” to avoid endless file-naming
FinalVersion1.docx
FinalVersion2.docx
UltimateFinalVersion1.docx
etc.
For single documents, cloud-based platforms have a Version History
e.g., in a Google Doc: File > Version History
For a larger project, with multiple files and folders, there are several tools, the most popular of which is currently Git
the most dominant tool worldwide for tracking and managing changes to software code and documentation
tracks an entire folder and everything underneath (not just a single file)
repository
the folder (and all its subfolders) that you’re tracking
runs on your computer (not online)
NOTE: Git works best with plain-text documents (UTF-8 encoding included), but not binary files like Microsoft Word or Excel documents
a web-based service (not on your computer)
centralizes Git repositories in the cloud
(literally an online hub for Git repositories)
simplifies collaboration
(Creative Commons license, courtesy of openclipart.org, image 278845, git-opensource-workflow, by developingo)
Now we’ll go through setting up the Git workflow for PsychoPy®
Git is free software for your computer
GitHub is an free online system, which you need to sign up for
download Git here
(the binary installer is easiest)
You can just choose the defaults
If you need it, the following YouTube video quickly shows you how to do this on both Mac and Windows
The Windows installation process involves clicking through more screens
Go to GitHub online
Click the following button: Sign up for GitHub
Provide your email, then create a password and username
Verify that you’re a human
Enter the launchcode that was sent to your email
You can accept the defaults through the rest of the options
If asked How many team members will be working with you?
Just answer with: Just me
What is forking on GitHub?
for most users
just copying an existing repository already on GitHub somewhere
and making it your own, on your own, online GitHub account
NOTE: Technically and more generally, it’s copying a repository, while also disconnecting it from other previous committers
While logged in to GitHub
Go to the search box at the upper left
type in: psychopy
You should see the following at the top of the search list: psychopy/psychopy
Click it
You should land here: https://github.com/psychopy/psychopy
You could also just type that URL in to your browser
Find the Fork pull-down menu located near the upper right corner
Choose the following: + Create a new fork
IMPORTANT: Be sure to UN-Check the box labeled as follows: Copy the ____ branch only
In other words, please copy all the branches
a fork is your own (online) copy (on GitHub) of the all the code required to build the current (in this case, release) version of PsychoPy®
it is “yours” in the sense that…
it is now disconnected from all other users
you are free to modify it
for your own purposes* (it’s open source, after all); or
in order to contribute back to the project (more common)
In fact, the latter is what you’ll be doing as translators
* though you still need to abide by the the particular license that applies to PsychoPy®
Command-line Git actually turns out to be very useful
You may eventually learn it anyway (responses to online requests for help often come in the form of the CLI)
But it is often intimidating at first
So there are many GUIs to make Git easier to use
popular, but relatively complex GUI tools for working with Git
GitKraken, PyCharm, Visual Studio Code, etc.
ideal starter option for translators:
Why?
free
retains the native terminology of Git
simpler, and therefore, less confusing
GitHub Desktop not natively designed for Linux
If you’re using Linux, try one of the following:
install the GitHub Desktop fork for Linux (see more options on the the shiftkey/desktop fork)
install GitFiend, which is cross-platform, but originally designed for Linux
just as easy to use as GitHub Desktop, perhaps easier
works on Windows and Mac as well
Go to the homepage for GitHub Desktop
Download and install the appropriate version
Linux users can easily download GitFiend
Cloning means downloading your online Git repository to your computer
Unlike forking it doesn’t disassociate anyone
It also establishes a connection between your local and online files
in GitHub Desktop on a Mac
GitHub Desktop > Settings > Accounts
Sign in using your credentials to GitHub.com (not GitHub Enterprise)
File > Clone repository
choose psychopy
(In GitFiend, you don’t sign in. You just provide the repository URL, which can be found in the GitHub repository under the <> Code button, where you then choose the Local tab, then the https link)
psychopy should be listed because it’s already forked in your online account
under Local Path at the bottom, choose a logical place on your computer for the cloned repository (e.g., not your desktop)
click Clone
This might take a minute, depending on your connection speed
full, updated* copy on your local computer of all the files from current release of PsychoPy®
including all the currently available localization folders
though you may need to add a new one (more on this soon)
Fully connected to your online fork of the repository on GitHub
* It’s updated at the moment you clone it, but as soon as someone else gets their commit(s) pulled in upstream, both your fork and its clone will be out of date. But there’s a way to deal with this (which is really the raison d’être of Git). I will cover this quite soon below.
origin
your fork of the original repository on GitHub
for your account, this is as follows
[your-github-account-name]/psychopy
e.g., johndoe/psychopy
upstream
the original repository on GitHub
always as follows for PsychoPy®
psychopy/psychopy
You have established the means to do the following:
add translations to PsychoPy on your own computer
push those changes to origin (i.e., your fork on GitHub)
then “suggest”* those changes to upstream (the original psychopy repo) through a pull request from origin
* You can’t push to upstream. Origin belongs to you. Upstream does not.
… but… what about the -flow in workflow?
The next section is about keeping your repository up to date
synchronize frequently with the upstream repository
any time you begin work, occasionally while you’re working, and when you’re done
helps you avoid merge conflicts
usually, when 2 different contributors change the same lines of code in different ways*
e.g., if 2 translators translate the same string
minor headaches to fix by maintainers
but better to avoid them altogether
* … but can also happen if you change the same line on different branches
Go to your fork online
(again, this is your copy of the psychopy repository on GitHub, aka origin)
Make sure you’re on the release branch
(The pull-down menu at the upper-left shouldn’t say dev, but rather release. Use that same pull-down menu to choose release if you have to)
Click: Sync fork (located a bit to the right)*
* Note that this can only do something if there is, indeed, something new to synchronize from upstream
Go back to GitHub Desktop on your local machine
Make sure you are on the release branch
Repository > Pull
This updates your local copy (your clone) with your fork (origin), which was just synchronized with the upstream repository
Now all three should be identical
Complete this step after the one before it, each time before you begin work on a new set of translations
The reason is that other translators on your team may have changed things since you last did, making your copy out of date
Branch > Merge into current branch
You will be given a choice of repos and branches, but DO NOT GO WITH THE DEFAULT*
Instead, choose upstream/release
- (it might help to type release into the Filter box)
Click the tab at the upper right, which should Push origin along with an arrow and a number (the number of commits that it’s pushing to origin)
* Currently, the default is upstream/dev for some reason. We don’t know how to change this in GitHub Desktop for the moment. Choosing that would merge the upstream dev branch into your local release branch, a disastrous merge.
Do not choose the following
Branch > Update from upstream/master
This would have the same disastrous effect as choosing the default (upstream/dev) in the previous slide
Yes, this slide is repeated
Why?
to emphasize that keeping one’s repository up to date is a common routine
not something that you do once and forget about
or only do occasionally
On to Working on translations