Introduction

The FirstVoices keyboards act as a way for language communities to type in their language both on computers and mobile devices. The FirstVoices keyboards for Mac and PC are built in partnership with Keyman, using Keyman's open-source technology. The FirstVoices keyboards from Chromebook are built using the FirstVoices Chromebook plugin. The keyboards are designed to function across online platforms, and to be useful while typing both the Indigenous language as well either English or French. This allows users to type in their language, but also to type characters that may not exist in their language but are prominent in English or French and thus necessary to successfully use the internet.

The FirstVoices team works to ensure the keyboards are up to date, and functioning are intended. However, there are occasionally have external users interested in either updating existing keyboards or creating new ones. This contributor guide will support you in doing this, and ensure that the appropriate steps are followed so that your keyboard or keyboard updates can be approved by the FirstVoices team. Contributions to our repository of keyboards are welcomed, and this page has a series of steps and guidelines to help support you in adhering to our process.

Before you start

Before you start creating a keyboard, or modifying the Keyman files on an existing keyboard, please reach out to the FirstVoices team at hello@firstvoices.com with the following information:

• Who you are, your Github handle, and what language you are working on
• Why you are looking to change or create a keyboard
• If you're changing an existing keyboard, what specific modifications are you planning and why
• Who from the language community you have consulted about this project and what was done during that consultation process
• How you plan to distribute and support this keyboard in the future
• For new keyboards, the language code (BCP-47) for your keyboard (reach out to us if you need guidance on determining this)
• Confirmation that you have read and agree to our terms (see bottom of this page), including our Contributor License Agreement. 

Doing this in advance will not only ensure that there is mutual understanding about what your plans are, it will also allow the FirstVoices team to communicate with the language team from that community, to confirm that these are changes they are interested in.

Once you have been approved to make modifications, you can move onto the next steps.

Building for Mac, PC or Mobile

Understanding Keyman

Keyman Developer is a complex program, and if you have never worked on a Keyman keyboard before, it is essential that you learn how to use the developer's tools before making any modifications to a keyboard.

• Click here to read the Keyman Developer User Guide
• Click here to read some general guidelines around contributing to Keyman keyboards.

Working in Keyman

Once you have a functional grasp of how to work in Keyman Developer, you will need to adhere to the following instructions about creating/modifying a FirstVoices keyboard:

• Your keyboard must follow FirstVoices' global Unicode standards (connect with us to get this). This means that all characters encoded into your keyboard must have the correct Unicode key points as outlined in this document.
• Your keyboard must follow the Unicode standards for that language's FirstVoices language site. This means that all characters encoded into your keyboard must have the same Unicode key points as displayed on the FirstVoices language language site. If there isn't a FirstVoices language site currently available, please let us know so that we can design an appropriate Unicode standard.
• Your keyboard must follow Keyman's best practices for rules, stores, virtual keys, etc. as described in the Keyman Developer User Guide.
• Your keyboard must follow Keyman's best practices for documentation, following the same protocol and documentation layout that other FirstVoices keyboards have.
• Your contribution (via a Pull Request) must include entries in a change log in a HISTORY.md file (example: HISTORY.md). If this file does not exist, you can create one. Your entries should describe what has been changed from the previous version, why, and by whom. As a reminder, changes to the keyboard name, copyright, or significant changes to the layout should be coordinated with the FirstVoices team during the "before you start" stage of this process.

Building for Chromebook

To learn how to build a Chromebook keyboard for the FirstVoices Keyboards plugin, click here for the tutorial.

Once you have a functional grasp of how to work in FirstVoices Keyboards plugin, you will need to adhere to the following instructions about creating/modifying a FirstVoices keyboard:

• Your keyboard must follow FirstVoices' global Unicode standards (connect with us to get this). This means that all characters encoded into your keyboard must have the correct Unicode key points as outlined in this document.
• Your keyboard must follow the Unicode standards for that language's FirstVoices language site. This means that all characters encoded into your keyboard must have the same Unicode key points as displayed on the FirstVoices language language site. If there isn't a FirstVoices language site currently available, please let us know so that we can design an appropriate Unicode standard.
• Your contribution (via a Pull Request) must include entries in a change log in a HISTORY.md file (example: HISTORY.md). If this file does not exist, you can create one. Your entries should describe what has been changed from the previous version, why, and by whom. As a reminder, changes to the keyboard name, copyright, or significant changes to the layout should be coordinated with the FirstVoices team during the "before you start" stage of this process.

Completing your Contribution

1. Once you are ready to contribute, create a Pull Request that includes all your changes against https://github.com/keymanapp/keyboards. Github has some more information on creating a pull request.

2. Keyman staff will review your pull request and provide feedback if applicable, specifically related to the keyboard functionality.

3. Once Keyman staff feedback is addressed, they will assign the PR for a mandatory review by a FirstVoices team member to ensure that it meets our contribution guidelines. 

4. After all applicable modifications have been addressed, and both reviews have passed, your changes will be merged into our repository.

5. You changes will be queued for the next release of the FirstVoices Keyboard app for all platforms. You may be invited to test the beta if you wish to do so!

Terms

In order to have a new keyboard or keyboard changes accepted into the FirstVoices keyboard repository, you must agree to the following:

• The keyboard and your work will fall under our Contributor License Agreement.
• The README should not be changed as part of your commit. If you have a reason to make changes to the README, please coordinate that in advance with the FirstVoices team.
• The keyboard must be approved by the FirstVoices team and, most importantly, the community's FirstVoices language team, pre- and post-development. No changes or additions will be submitted to Keyman until there is this approval.

We welcome contributions in developing a new keyboard to be added to the FirstVoices keyboards package, or modifying an existing FirstVoices keyboard! Please contact hello@firstvoices.com with the information listed under "Before you start" and a member of the FirstVoices team will contact you for further discussion.