You have already practiced this workflow, but here is some more information
stage (local copy)
commit (local copy)
push (local copy to origin)
pull request (origin to upstream)
clean up (if you’re working on a branch you created)
answer:
ALL changes in a directory (where the hidden .git folder resides) and its subdirectories
unless you list that file or file type in the .gitignore file
what should you put into a single commit?
just related changes
unrelated changes in a single commit can lead to a confusing version history
this is the purpose of staging
Look at the far left under the tab labeled as follows: Changes
If a file is staged, it has a checkmark next to it
If you don’t want that file to go into your next commit, you’ll need to un-check it
To un-check the boxes, un-check the top box
This will un-stage everything
Next, check the boxes you want to stage for your next commit
After the initial setup, most translators will be working on just a few files anyway, i.e.:
mappings.txt
messages.po
(and maybe) tips...txt
At the bottom of the same tab, Changes, you’ll see two boxes
The one on top says: Summary (required)
The one below that says: Description
The top one is a commit message
required by Git for every commit
(there is no way around this)
The bottom one, Description is optional
convention established by the maintainers at PsychoPy®
append an UPPERCASE prefix to every commit message
Examples:
BF:
for bug fix
FF:
for feature fix
help maintainers search for key changes to the project
Otherwise, they’d have to sift through all changes to a project when, say, they knew they only wanted to search through bug fixes (BFs)
for all translations:
DOCS:
usually for documentation
but also for changes that cannot “break” the software
DOCS: may change to something like TRNSL: in future
Jon Peirce will let you know if this change occurs
summary of what all the changes in the commit do as a single unit
The standard convention is to start with a verb in the imperative mood (i.e., a command)
For example:
DOCS: Add translations to Portuguese in Brazil
DOCS: Add start-up tips to Modern Standard Arabic
Use English, naturally, as the maintainers at PsychoPy® probably don’t speak your language
Remember that there is a 50-character limit
Sometimes commit messsage is clear
DOCS: Add start-up tips to Yoruba in Nigeria
Sometimes not possible
This is when you use a description
No character limit
but try to be succinct
more than 100 characters?
split your commit into two or more commits?
NOTE: All that said, messages alone should suffice in almost all translation cases
When your changes are ready and staged, and you have a commit message
Click the button at the bottom of the same tab:
Commit to release
NOTE: If you’re contributing to PsychoPy® in other ways, you probably want to make sure you add a new branch for translations.
The commit is like sealing an envelope you want to send in the mail
It’s still just on your computer
You still need to “mail it in” to your online repository
This is done through a push
can push directly to your own fork on GitHub
cannot push directly to the main, upstream, repository at https://github.com/psychopy/psychopy
If just anyone could do that, the whole open-source world would probably collapse
Instead
first push to your fork at origin
Then go to your fork on GitHub and make a pull request from there to upstream
NOTE: You can make a pull request directly from GitHub Desktop, but I’m not completely sure what the implications of that are. I’m scared of it, to be honest.
Select the following:
Repository > Push
Or click the Push origin tab
(this should have replaced the Fetch origin tab at the upper-right)
changes should be on origin (online)
should see a note saying that you’re one commit ahead of upstream
This is good
your translations are new, and need to be incorporated into the main project
To initiate the process of making them identical, you need to make a pull request
terminology a little counter-intuitive
You’re not asking permission to pull changes yourself
Rather, you’re “requesting” that the maintainers of upstream “pull” your changes in
like “Pull me in, please.”
(if that helps)
Go to your fork of the repository on GitHub (i.e., origin)
Select the branch that you just made the commit to
probably release, but possibly something like portuguese-translations if you have other projects (e.g., bug fixes)
Branches are located in a little pull-down menu at the upper left
Once there, GitHub should indicate that your latest commit is probably awaiting a pull request to upstream
Look for a banner at the top with a note about the recent commit, and a green button with the following message: Compare and pull request
Click that button
But if it’s not there
you can start a pull request from either of the following:
the Pull requests tab at the top
the Contribute tab next to the left of the Sync fork tab
You should now be switched to the upstream repository at psychopy/psychopy
And you should see a screen with the following title: Comparing changes
There should be 4 pull-down menus, labeled as follows on the next slide, from left to right
base repository: psychopy/psychopy (this refers to the upstream repository)
base: release (the appropriate branch on upstream to merge into)
← (showing you the direction of the pull request)
head repository: [your own GitHub account]/psychopy (this refers to your forked origin repository)
compare: release (the appropriate branch on origin to merge from [unless you created a new branch])
WARNING: If you see many more file changes than you were expecting, then you might be on the wrong branch
NOTE: If it says There isn’t anything to compare, you probably didn’t yet push the commit from your local copy to origin
Hopefully, you see the following directly below the information covered in the last slide
a green check mark
a message next to it that says the following:
Able to merge. These branches can be automatically merged.
If you do not, then one of the following might have occurred
You are trying to merge to or from the wrong branch (or both)
Double check your branches (see previous slide)
Another translator has worked on the same files on the same translations, and then submitted a pull request before you did
In this case, you could have a merge conflict
Contact one of the maintainers
They can fix it
It’s not a big deal
description
optional
can be useful to administrators if the changes are complex
answers the what, why, how, etc. of the pull request
truth be told, descriptions generally won’t be of much use to translators unless you’ve done something unusual, and I can’t think of anything that would be unusual.
A pull request for a translation is only going to involve 1-3 files (though there may be many, many lines changed)
But even if there are many lines changed, the administrators at PsychoPy® will probably not be able to review translations in much detail since they probably won’t speak the language
From the last slide
the administrators at PsychoPy will probably not be able to review translations in much detail since they probably won’t speak the language
In this sense, translators carry more responsibility than even someone adding new features to PsychoPy®
This is because administrators will probably be forced to authorize your proposed changes without checking them
Translate responsibly
If you make further commits before the pull request is merged in by the administrators
don’t worry
your commits will automatically be incorporated into the previous pull request
Again!!??
Yes
From GitHub on your fork
(Make sure you are on the release branch)
Sync fork (from upstream)
From GitHub Desktop
Repository > Pull
On to A strategy for later on