This file provides the steps for doing some of the tasks you may want to do when contributing to the AutoKey project. The information is divided into four sections:

• The Basic GitHub Workflow gives you an idea of what the workflow looks like.
• The Local section is for things you can do on the command-line.
• The Remote section is for things you can do on GitHub in your browser.
• The Notes section is for things that don't fit anywhere else.

The Local and Remote sections are alphabetized and do not necessarily present the entries in the order in which you would use them.

---

These steps take you through the basic workflow for using GitHub in your browser to contribute to the AutoKey project in a beginner-friendly way.

1. Fork a remote repository:
   1. Go to the repository's main page.
   2. Click the Fork button in the top right corner.
   3. Choose an owner for the fork if you like (it will be you by default).
   4. Change the name of the fork if you like (it will be the original repository's name by default).
   5. Change the description if you like (it will be the original repository's description by default).
   6. Uncheck the Copy the master branch only box (this is important).
   7. Click the Create fork button. Note that once the forking process is complete, you'll automatically be at the main page of your new forked repository.
2. Open the branch you'd like to work on.
3. Create a new branch off of that branch with a name that lets you know what kind of change you're about to make. Note that this will be a temporary branch that's for your use only and won't be copied to the remote repository that you forked from.
4. Make one or more changes to files inside the new branch with one of these methods:
   • Use the GitHub editor to make the changes, committing each one with a comment describing what you did.
   • Use the command line to clone your fork, make the changes, and push them to your fork.
5. Update the CHANGELOG.rst file to note the change(s).
6. Start a pull request with any one of these methods:
   • Click the Compare & pull request button above the file list.
   • Click the link in the note above the file list that tells you that this branch is ahead of the branch your changes will be made in.
   • Click Pull requests in the top menu and then click the Compare and pull request button.
   • Click Pull requests in the top menu and then click the New pull request button.
7. Check the information in the grey section at the top to make sure that:
   • the base repository is the remote repository that you forked
   • the base is the remote branch that you want to change
   • the head repository is your fork
   • the head or compare is the branch that contains your change(s)
8. Scroll down to review the change(s) you made to the file(s).
9. When you're satisfied with the settings and your changes, click the Create pull request button.
10. Wait for the tests to complete and verify that you have an Able to merge message from GitHub.
11. Type a meaningful title for the pull request into the top text box to give the remote repository's maintainer a quick idea of the reason for this pull request.
12. Optionally, type a detailed comment into the Write text box, letting the remote repository's maintainer know more about the change(s) that you've made.
13. Click the Create pull request button.
14. You'll be notified by email once the remote repository's maintainer has merged the pull request into the remote repository. You can then delete the temporary branch you had created in your fork in step 3 above or delete the entire fork:
    1. Go to the remote repository's main page.
    2. Click the Pull requests entry in the menu.
    3. Click Closed in the heading above the list of pull requests on that page.
    4. Click on the name of your pull request.
    5. Scroll down to the Pull request successfully merged and closed section at the bottom.
    6. Click the Delete branch button in that section to delete the branch and keep the forked repository or, if you no longer want the forked repository, click the settings link in that section.
    7. The next time you open the affected branch in your fork, GitHub will notify you at the top of the file listing that your branch is out-of-date. This is because the changes you made in your temporary branch have now been made in the base branch you chose in the remote repository and they now need to be made in your fork so the two repositories can be identical. To synchronize them:
       1. Click the Sync fork button to the right of that message.
       2. Click the Update branch button.

As an example, if you created the foo branch off of the develop branch in your fork, changed the contents of its readme.txt file, did a pull request, chose develop as the base, and chose foo as the head, the readme.txt file in the remote repository's develop branch will be the file that changes. The remote repository will not get a copy of your foo branch and you'll be able to delete the foo branch once the pull request is merged into the remote repository.

If, instead of following the above steps and editing a file in your fork, you attempt to edit a file in a repository that you don't have push rights to (the AutoKey repository), when you commit the change(s), GitHub will automatically offer to create a branch with the default name of patch-1 (or patch-2, etc., depending on whether other patch branches exist). You can edit the branch name if you like. That branch gets created in the remote repository you don't have push rights to (in this case, the AutoKey repository) when you do a pull request and it's accepted, and it's the branch that's used as the base for the pull request. Your fork will then get a copy of that branch the next time you sync the branches. If you then view the branches in your fork, you'll see that you own that branch. Once the pull request is accepted, you can delete the branch from your fork and it will be automatically deleted from the remote repository that you don't have push access to without a pull request.

---

1. Open the repository's home page in your browser.
2. Click Pull requests in the toolbar.
3. Get the number of the pull request from its description in the list.
4. Open a terminal window in the directory in which you'd like to create the clone's subdirectory.
5. Clone the AutoKey repository:

   git clone https://github.com/autokey/autokey.git
   

6. Press the Enter key to create the autokey subdirectory inside of the current directory.
7. Change to the directory you just created:

   cd autokey
   

8. Fetch the pull request by its number and put it into the specified new branch (replace 844 with your pull-request number):

   git fetch origin pull/844/head:pull_844
   

9. Change to the new branch you just created (replace 844 with your pull-request number):

   git checkout pull_844
   

1. Open the repository's main GitHub page in your browser (note that this can be one of your repositories or a remote repository not owned by you).
2. Click the Code button.
3. Click the clipboard icon to the right of the URL.
4. Open a terminal window in the directory in which you'd like to create the clone's subdirectory.
5. Create the clone in the autokey subdirectory inside the current directory: git clone https://github.com/autokey/autokey.git

1. Click here to toggle VirtualBox installation instructions.

   ---

   One of the popular virtual-machine programs is VirtualBox. Below are basic instructions for installing it:

   1. Go to the VirtualBox LinuxDownloads page.
   2. Click your distribution's name in the list to download a .deb file.
   3. Click the SHA256 checksums link to download a list of SHA checksums.
   4. Click the MD5 checksums link to download a list of MD5 checksums.
   5. Open a terminal window in the download folder on your computer.
   6. Run this command to generate the SHA checksum for the .deb file you downloaded: sha256sum virtualbox*.deb
   7. Compare the result with the SHA checksum matching your Linux distribution in the SHA256SUMS file you downloaded to make sure they're identical. If they're not, delete the .deb file and go back to step ii above.
   8. Run this command to generate the MD5 checksum for the .deb file you downloaded: md5sum virtualbox*.deb
   9. Compare the result with the MD5 checksum matching your Linux distribution in the MD5SUMS file you downloaded to make sure they're identical. If they're not, delete the .deb file and go back to step ii above.
   10. Install VirtualBox by double-clicking the .deb file in your file manager or by running this command: sudo dpkg -i Virtual*.deb
   11. Install the dependencies for VirtualBox and configure VirtualBox with this command: sudo apt-get install -f
   12. Once VirtualBox is installed, you should find a shortcut to it in your main menu (possibly in the System section of your menu under the name of Oracle VM VirtualBox).

   ---

2. Download an .iso file from a Linux distribution onto your host computer.

3. Put the ISO into your default machine folder (if you don't remember where that is, click the File menu in VirtualBox, choose Preferences... from the context menu, and look in the Default Machine Folder text box.

4. Open VirtualBox.

5. Click the New entry in the Machine menu or click the New button in the center panel.

6. Give your virtual machine a meaningful name.

7. Click the ISO Image drop-down arrow and choose the ISO you just downloaded.

8. Put a check-mark in the Skip Unattended Installation box.

9. Click the Next button.

10. Examine and optionally adjust your hardware settings.

11. Click the Next button.

12. Examine and optionally adjust the Virtual Hard disk settings.

13. Examine the Summary and click the Next button if you're satisfied. Otherwise, click the Back button and make changes.

14. Double-click the new virtual machine in the left pane of VirtualBox.

15. Follow the on-screen instructions to install the operating system in the virtual machine.

After cloning a repository, if you've messed up the changes you've made to the files or if you're done working on the code, you can just delete the clone's directory inside of your virtual machine. This will have no effect on the remote repository you cloned it from.

Make any changes you feel are needed in the local files in your clone. Note that this has no effect on the remote repository unless you push the changes back to the remote repository.

1. (Optional) Boot into the virtual machine.
2. Grab all available operating-system updates.
3. Update the apt database: sudo apt update
4. Install pip3: sudo apt install python3-pip
5. Install tkinter: sudo apt install python3-tk
6. Install Xvfb: sudo apt install python3-pytest-xvfb
7. Install tox: sudo apt install tox
8. Create a GitHub personal access token.
9. Configure your git username by replacing John with your username: git config --global user.name "John"
10. Configure your git user email by replacing John Doe's email address with yours: git config --global user.email "[email protected]"
11. (Optional) Configure your git editor as nano instead of the default of vim: git config --global core.editor "nano"
12. (Optional) Configure your git pushes to tracking so that they'll go wherever they're being tracked to go automatically based on your clone command: git config push.default tracking

Once a clone is on your system, you can run the cloned copy of AutoKey without installing it by using either of the commands below. This section assumes that you cloned the repository onto your desktop, so you'd want to edit the commands to suit the path to your clone.

1. Open a terminal window.
2. Pick one to run AutoKey:
   • Run AutoKey from anywhere with its full path:
     1. Open a terminal window.
     2. Pick one, replacing ~/Desktop/autokey with the path to your clone:

        • AutoKey GTK:

          cd ~/Desktop/autokey; cd lib; python3 -m autokey.gtkui -lc
          

        • AutoKey Qt:

          cd ~/Desktop/autokey; cd lib; python3 -m autokey.qtui -lc
          

   • Run AutoKey from inside the lib subdirectory:
     1. Open the autokey directory in a terminal window.
     2. Change to the lib subdirectory:

        cd lib
        

     3. Pick one:

        • AutoKey GTK:

          python3 -m autokey.gtkui -lc
          

        • AutoKey Qt:

          python3 -m autokey.qtui -lc
          

3. When finished, close AutoKey.
4. Close the terminal window.

GitHub Actions can be run locally on your machine or inside of your virtual machine.

1. Open the clone's directory in a terminal window.
2. Choose a testing command to run:
   • Run a lint test: tox -e lint
   • Run all tests for all platforms in all environments: tox
   • Run all tests for all platforms in the environment that tox is installed in: tox -e test
   • Run all tests for all platforms in all environments, recreating the virtual environments first: tox -r
   • Run all tests for all platforms in all environments, recreating the virtual environments first: tox --recreate
   • Run all tests for the specified platform in the specified environment: tox -e py37-test
   • Run all tests for the specified platforms in the specified environments: tox -e 'py3{7,11}'-test
   • Run all tests for all platforms iusing the version of Python in PATH: tox -e py
   • Run all tests for the specified platform in all environments: tox -e py37
   • Run individual tests on specified files that start with test_:
     • Run an individual test on the specified file: tox -- tests/create_single_phrase.py
     • Run an individual test on the specified file: tox -- tests/engine_helpers.py
     • Run an individual test on the specified file: tox -- tests/test_common.py
     • Run an individual test on the specified file: tox -- tests/test_configmanager.py
     • Run an individual test on the specified file: tox -- tests/test_iomediator.py
     • Run an individual test on the specified file: tox -- tests/test_macro.py
     • Run an individual test on the specified file: tox -- tests/test_phrase.py
     • Run an individual test on the specified file: tox -- tests/test_phrase_runner.py
   • Run the clean, coverage, and report tests: tox -e clean,coverage,report

When interpreting the test results, note that tests can be marked by the developers with skip or xfail if they're expected to fail for some reason, as they might be with a feature not implemented yet or an unfixed bug.

• Marking a test with skip will prevent that test from being run at all.
• Marking a test with xfail will run that test so you can check if it still fails or not.

• SKIPPED means that a test marked with skip wasn't tested, as expected.
• XFAIL means that a test marked with xfail failed the test, as expected.
• XPASS means that a test marked with xfail passed the test.

If you've got what seems like a good working copy of the code, it's time to build it into files that can be installed on a machine so you can try it out and see if it works.

TODO: Find out if there's any difference between doing the build from the zip file, the way we do here, and doing it from a a cloned copy of the fork.

1. Open your virtual machine.

2. Open a browser inside the virtual machine.

3. Go to the repository's main page on GitHub.

4. Choose the branch that you'd like to build.

5. Click the Code button.

6. Click Download ZIP from the drop-down menu.

7. Extract the zip file, creating a directory that contains the contents of the repository.

8. Open that directory in a terminal window.

9. Pick one:

   • Install AutoKey:

     pip3 install .
     

   • Build AutoKey:

     1. Build the packages in the parent directory: dpkg-buildpackage -us -uc

     2. Test the build:

        1. Change to the parent directory: cd ..
        2. Install the GTK version: sudo dpkg --install autokey-gtk_<version>.deb autokey-common_<version>.deb
        3. Install the Qt version: sudo dpkg --install autokey-qt_<version>.deb autokey-common_<version>.deb
        4. Install any missing dependencies: sudo apt install -f
        5. See if the build works, where it puts AutoKey, and any messages/errors it generates.
        6. If everything works, copy the .deb files it produced to a clean virtual machine and see if they'll install and work properly there.

        TODO: An alternative may be to run autokey/debian/build.sh to build the .deb files, but I'm thinking that will be run automatically when following the steps above. I'll update this once I do a successful build.

If there are changes to the remote repository, you'll want to update your clone. To do that:

• Pick one:

  • Update the current branch with changes from the remote repository:

    git pull
    

  • Check what's new on the remote repository before updating the current branch:

    1. Check what has changed in the remote repository on the current branch:

       git fetch
       

    2. Update the current branch with the change(s):

       git merge
       

---

To put a link to your official documentation or any other website that you like in the right panel of your repository's main GitHub page:

1. Go to your repository's main page.
2. Click the gear next to About in the right panel.
3. Paste the URL into the Website box.
4. Save the change.

Archive a repository:

1. Go to the main page of the repository.
2. Click the Settings in the menu.
3. Scroll down to the Danger Zone section.
4. Click Archive this repository.
5. Read the warnings.
6. Type the name of the repository.
7. Click I understand the consequences, archive this repository.

Unarchive a repository:

1. Go to the main page of the repository.
2. Click the Settings in the menu.
3. Scroll down to the Danger Zone section.
4. Click Unarchive this repository.
5. Read the warnings.
6. Type the name of the repository.
7. Click I understand the consequences, unarchive this repository.

The standard bug report on GitHub is ordinary Markdown. You can create a YAML issue template form that's interactive instead.

1. Create the .github/ISSUE_TEMPLATE/bug.yaml file while you're in the main branch of your repository. That will create the .github folder inside of the main branch, the ISSUE_TEMPLATE folder inside of that one, and the bug.yaml file inside of that one.
2. Populate the bug.yaml file with your YAML code.
3. Commit the change.

If you'd like to prevent blank issues from being used and ensure that your users will use your issue template:

1. Create the config.yml file inside of the /.github/ISSUE_TEMPLATE folder.

2. Paste or type this line into it:

   blank_issues_enabled: false
   

3. Save the file.

4. Commit the change.

GitHub offers a way to create a folder, but you cannot create an empty folder, so the idea is that you create a file and specify a folder for it to go into as part of the creation process.

1. Open the branch you'd like to create a folder in.
2. Click the "Add file" button.
3. Type a new folder name followed by / followed by a new file name into the text box. Note that if you regret the folder name you just typed in, typing .. followed by / will remove it or you can use the backspace key to edit the parent folder's name.
4. Click the "Commit new file" button to create the folder and file and enter the folder.

Note that you can apparently drag a folder with at least one item inside of it from your computer into the GitHub repository page, but I haven't tested that.

You can create and manage milestones (goals) for your GitHub project:

1. Open your GitHub repository's main page.
2. Click Issues in the menu.
3. Click the Milestones tab next to the New issue button.

GitHub's saved replies offer you a way to store snippets of boilerplate text and use them in any comment box on GitHub.

1. Click on your GitHub profile image.
2. Click Settings in the drop-down menu.
3. Click Saved replies in the Code, planning, and automation section in the left pane.
4. Type a title for your saved reply into the Saved reply title text box.
5. Type a reply into the Write text box.
6. Preview your reply in the Preview tab and go back to the Write tab to edit it if you'd like to make changes.
7. Click the Add saved reply button to store the saved reply.

Now, you'll be able to click the little curved arrow above any comment field on GitHub and select that reply by its title in the drop-down list that opens.

See the Basic GitHub Workflow section above.

1. Log into your GitHub account.
2. Select your repository.
3. Open the Settings tab.
4. Open the Options tab.
5. Scroll down to the Features section.
6. Activate the issue tracker by putting a check-mark in the Issues box.

1. Go to the repository's main page.
2. Click the Fork button in the top right corner.
3. Choose an owner for the fork if you like (it will be you by default).
4. Change the name of the fork if you like (it will be the original repository's name by default).
5. Change the description if you like (it will be the original repository's description by default).
6. Uncheck the Copy the master branch only box (this is important).
7. Click the Create fork button.

If you'd like quick access to one of your gists or repositories from now on:

1. Go to your GitHub home page.
2. Click Customize your pins in the right center of your home page.
3. Put a check-mark in the box next to the gist or repository you'd like to pin.
4. Click the Save pins button.

This must be done on the command line with git.

1. Open your repository on GitHub.
2. Click the Pull requests tab.
3. Click the pull request that you'd like to revert.
4. Click the Revert button. Note that this will create a new pull request that reverts the changes.
5. Submit the resulting pull request.

Once your code has been accepted and merged into a project, you can delete the fork. Deleting a fork will have no effect on the project it was forked from.

1. Go to your local repository's (the fork's) main page.
2. Click on Settings in the top menu.
3. Scroll to the bottom of the page to the Danger Zone section.
4. Click the Delete this repository button.
5. Type in your GitHub username and repository's name at the prompt.
6. Click on the I understand the consequences, delete this repository button.

All of these examples are searching for foo in the wiki and you can change that to whatever you'd like to search for:

• Put this into the search bar at the top left corner of Github: user:autokey foo
• Or put this into the search bar: user: autokey repo:autokey foo
• Or put this into the search bar: repo:autokey/autokey foo
• Or use this link: https://github.com/search?type=Wikis&q=repo%3Aautokey%2Fautokey+foo

To search by last-updated date, the updated qualifier matches wiki pages that were last updated within the specified date range. When you search for a date, you can use greater than, less than, and range qualifiers to further filter results. For more information, see the Understanding|the search syntax page. Some example searches:

• Match wiki pages containing the word "foo" that were last updated after 2016-01-01: foo updated:>2016-01-01
• Match wiki pages that were last updated before 2016-01-01: repo:autokey/autokey updated:<2016-01-01
• Match wiki pages that were last updated after 2016-01-01: repo:autokey/autokey updated:>2016-01-01
• Match wiki pages that were last updated on or before 2016-01-01: repo:autokey/autokey updated:<=2016-01-01
• Match wiki pages that were last updated on or after 2016-01-01: repo:autokey/autokey updated:>=2016-01-01

---

• The .tox directory grows each time the tox command is run. It can be manually removed, removed internally if its output contains no errors, or it can be destroyed and recreated each time.
• Tagged releases merged onto beta or master will automatically be built.

• apt packages: Do a search for a package (replacing foo with the package name): https://packages.ubuntu.com/search?suite=jammy&arch=any&searchon=names&keywords=foo
• Exit codes for the tox command: https://docs.pytest.org/en/stable/reference/reference.html#exitcode
• GitHub available images: Do a search for latest on here to find out which version of Ubuntu is currently considered the latest: https://github.com/actions/runner-images#available-images Then check its current Python or other software versions, check for announcements, etc.
• GitHub Python Versions Manifest: Do a search for an Ubuntu release number (for example, 24.04) and find all hits to let you know which are the lowest and highest versions of Python supported for that Ubuntu release: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json
• Python packages: https://pypi.org
• Ubuntu manifest - current: Example for 24.04: https://releases.ubuntu.com/24.04/ubuntu-24.04.1-desktop-amd64.manifest
• Ubuntu manifests - old: Click on any old or current release to find and download its manifest from: https://old-releases.ubuntu.com/releases/