Unfamiliar with git: best way to update my keyboard?

Keyman Keyman How To
1

I’ve read the guide here: Guide: Keyboard Submissions using GitHub

And a year ago I managed to fork and submit my ausephon keyboard (with help from the SIL community).

Now I want to submit a new version of my keyboard. What is the best way to do that? I began by editing the files one-by-one on the git web interface and submitting pull requests for each one (LOL) but I was concerned that might create too much work for SIL admins so I cancelled each request.

ausephon keyboard (keyman.com)

If there is another post on the forums that answers my question, I apologise in advance and thank you for directing me to it.

2

Hi Ben. I guess we should add a section to that guide on how to update an existing keyboard. Would you like to test what I have just drafted?!

Outline:

  1. Update your fork of the keyboards repository
  2. Make sure you have a copy of the latest files that are on the repository
  3. Update the keyboard files on your computer and test
  4. Submit your updates as a new pull request

Details:

  1. Update your fork
  • See the " Updating your fork" section at the end of the Step 3: Submitting a GitHub Pull Request page for instructions on updating your fork. (I see that the “Fetch Upstream” button is now labeled “Sync fork”.)
  1. Make sure you have a copy of the latest files that are on the repository

One way to make sure you have the latest files for your keyboard is to download that folder from your newly-updated fork.

  • Go to https://github.com/[YourGitHubName]/keyboards/ (after replacing [YourGitHubName] with your actual GitHub name)
  • Navigate to the keyboard, for example, to “release”, then “a”, then “ausephon”
  • At that point the browser URL will be something like:
    https://github.com/[YourGitHubName]/keyboards/tree/master/release/a/ausephon
  • Copy this URL
  • Go to: https://download-directory.github.io/
  • Paste the URL into the field and press Enter
  • The files for the keyboard are zipped up and offered for download as:
    keymanapp keyboards master release-a_ausephon.zip
  • Rename the file to ausephon.zip and save. (Or save first, then rename.)
  • Unzip ausephon.zip to get the keyboard project folder ausephon with all its files and subfolders.
  1. Update the keyboard files on your computer and test
  • Double-click on the ausephon.kpj (Keyman project file) in the ausephon folder to launch Developer
  • Make your changes
  • Build and test the keyboard, then build the package
  • When everything is updated (included changes to the HISTORY.md file and, if necessary, to the LICENSE.md file), you’re ready to submit the changes, but first…
  • Delete the build folder and the files in it
  • Delete the .kpj.user (but don’t delete the .kpj file!)
  1. Submit your updates as a new pull request, essentially following the instructions in Step 3: Submitting a GitHub Pull Request except that the target keyboard folder will already be there.
  • Create a new branch (from master)
  • Navigate to the target folder location (click on release, then on a, and you’ll see the ausephon folder)
  • Click on “Add file”, then “Upload files”
  • Drag the “ausephon” folder from your Windows Explorer window and drop it on the GitHub window
  • Follow the steps to create a pull request, although the commit message will be something like [ausephon] updated keyboard

Let me know if this works for you. Any feedback welcome!

2 Likes
3

Thanks (once again) David for your detailed and very helpful response.

I have done my best to follow the instructions above. Perhaps you could confirm I’ve followed the instructions correctly and then I could share my feedback on the instructions?

Very best wishes,

B

4

I mean - I’ve just now submitted a pull request for all the new files! B

5

I haven’t looked at the individual changes, but overall it seems that you’ve successfully submitted a pull request updating this keyboard. Congratulations! Someone will review the files in the next few days.

Having said that, I see that you’ve added Charis SIL font files to the keyboard. These font files are used in multiple keyboards, so we have placed them under a “shared” folder and prefer that those versions be accessed (rather than each keyboard having its own copy). This enables us to update fonts in one place rather than requiring us (or keyboard authors) to update each occurrence of the fonts.

So, I guess I need to add another section describing how to do that using GitHub!

6

Thanks David for this guide - without any edits it successfully empowered me to submit updates to my keyboard.

As a token of thanks, here is some feedback from me on the guide from my perspective as ‘English teacher’ and ‘less technical user’.

Each numbered step in the OUTLINE might be made more distinct with unique ‘command verbs’ such as 1.Update, 2.Download, 3.Edit, 4.Submit.

Also a few familiar objects such as ‘ZIP file’ or ‘Keyman app’ might help orient this same reader.

My version:

  1. Update/synch your fork of the keyboards repository.

  2. Download a copy of the latest files that are in your repository as a ZIP file.

  3. Edit the keyboard files on your computer using the Keyman app or a text editor.

  4. Submit your updates as a new pull request

In the DETAILS section, Step 1, I ended up doing this before anything else:

The web interface is rather ‘information overload’ otherwise.

At Step 4, I wasn’t sure what I should name my new branch (from master). I ended up calling my new branch ‘ausephon11’ (to distinguish this from my older branch named ‘ausephon’). Perhaps this is personal preference?

1 Like