Skip to content

Latest commit

 

History

History
475 lines (381 loc) · 23 KB

CONTRIBUTING.md

File metadata and controls

475 lines (381 loc) · 23 KB
Raw

Contributing to Keyman

⭐ Thank you for your contribution! ⭐

The following is a set of guidelines for contributing to Keyman, Keyman keyboards, Keyman lexical models and Keyman websites, which are hosted in the Keymanapp Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

(These guidelines have been adapted from Atom Guidelines.)

Table Of Contents

Code of Conduct

I don't want to read this whole thing, I just have a question!!!

What should I know before I get started?

How Can I Contribute?

Style Guides

Additional Notes

Code of Conduct

This project and everyone participating in it is governed by the Keyman Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

I don't want to read this whole thing I just have a question!!!

Note: If you have a question about using Keyman, you'll get faster results by asking in the Keyman Community, where many other users may also be able to assist you. If you have a question about the Keyman source code, feel free to open an issue!

What should I know before I get started?

Keyman, Keyboard Layouts and Lexical Models

Keyman is a complex project that spans six different platforms, with many a variety of components on each platform. We have chosen to host the Keyman project in the keymanapp/keyman monorepo, but keyboard layouts and lexical models are stored in their own repositories.

  • Issues relating to the Keyman apps and their interactions with operating systems or other apps should be opened in the Keyman repo
  • For keyboard-specific or model-specific issues, open issues in the corresponding repository.
  • The Keyman websites are also hosted in their own repositories. Contributions, including issues and pull requests can be opened against these repositories also.
  • Product documentation for the Keyman app is hosted in the Keyman app repository, and replicated to the help.keyman.com repository.

The primary repositories you are most likely to interact with are:

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report for Keyman. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.

Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template; the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Before Submitting A Bug Report

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template (not all repositories currently have a bug reporting template; in those cases, you can start with the Keyman bug report template if you wish).

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.

  • Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don't just say what you did, but explain how you did it. For example, if you typed on Android using a bluetooth keyboard, instead of with the touch keyboard, note that.

  • Provide specific examples to demonstrate the steps If you are documenting a problem with unexpected output from a keyboard, make sure you include the exact keystroke sequence you typed, the output you received, and the expected output.

  • Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.

  • If you're reporting that Keyman crashed, include the reference number from the crash report, if available.

Provide more context by answering these questions:

  • Did the problem start happening recently (e.g. after updating to a new version of Keyman, keyboard, app or operating system) or was this always a problem?
  • If the problem started happening recently, can you reproduce the problem in an older version of Keyman? What's the most recent version in which the problem doesn't happen? You can download older versions of Keyman from the Downloads page.
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

Include details about your configuration and environment:

  • Which version of Keyman are you using? The version information is typically available in the About or Info screen, depending on your device type.
  • What's the name and version of the OS you're using? Note exactly which type of device you are using, the version of the operating system.
  • Are you running Keyman in a virtual machine? If so, which VM software are you using and which operating systems and versions are used for the host and the guest?
  • Which keyboards and models do you have installed? You can get that list by running apm list --installed.
  • What app are you interacting with? If the problem is in interaction with a specific app, note the app you are trying to work with, and its version.
  • Which keyboard layout experiences the problem? Capture the keyboard ID and the version of the keyboard layout. On Windows, tell us also the base keyboard layout, found in Keyman Configuration, Options tab.
  • Diagnostic reports On Windows, you can capture a diagnostic report by clicking Diagnostics in the Support tab of Keyman Configuration, save it and attach it to the issue.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for Keyman, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion 📝 and find related suggestions 🔎.

Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed.

Before Submitting An Enhancement Suggestion

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. After you've determined which repository your enhancement suggestion is related to, create an issue on that repository and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of Keyman which the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
  • Explain why this enhancement would be useful to most Keyman users.
  • List some other keyboard tools or operating systems where this enhancement exists.
  • Specify which version of Keyman you're using. The version information is typically available in the About or Info screen, depending on your device type.
  • Specify the name and version of the OS you're using.

Your First Code Contribution

Unsure where to begin contributing to Keyman? You can start by looking through these good-first-issue and help-wanted issues:

  • Good first issues
    • issues which should only require a few lines of code, and a test or two.
  • Help wanted issues
    • issues which should be a bit more involved than Good First Issues issues.

Building Keyman

Keyman can be built locally. For instructions on how to do this, see the build documentation.

Localize Keyman

We use CrowdIn to develop translations for the Keyman user interface.

Other Ways of Getting Involved

Even if you are not a coder, there are many other ways you can help with the Keyman project:

Style Guides

Principles of Keyman Code Changes

These are some general principles that we need to be following when we create features or bug fixes in Keyman. These principles help to uphold a good user experience for Keyman end users and keyboard/model developers.

Pull Request and Commit Workflow

We have a number of git commit and pull request formatting preferences. We can review your pull request faster if you follow these guidelines:

Code Style Guide

The Keyman style guide will help you to prepare code in a way that matches the Keyman source. Note that older source may not yet meet this guide, so if you are fixing up an old piece of code, you may need to use your judgment to determine the code styling to use.

User Testing

Any pull request that impacts end user experience should include a user test. This is a set of instructions that an experienced user of Keyman could follow to validate that your pull request does what it should do. A good tester may depart from the test steps you provide to check the things you forgot -- but you should try and provide comprehensive test steps.

The Keyman app repository has a bot which coordinates user testing for each pull request:

Documentation Style Guide

This applies to user documentation found both on help.keyman.com and the application user documentation found in the Keyman repository. Remember that application documentation is replicated to help.keyman.com but should be edited in the Keyman repository.

  • All new documentation pages should be written in Markdown.
  • Older documentation may be written in HTML or a strange hybrid of PHP scripts and HTML. If you make more than a minor change to an older doc, rewrite it to Markdown:
    1. View Source on the page from your browser
    2. Find the documentation content (often within the <article> tag)
    3. Use a tool such as Browserling HTML to Markdown to convert the document to Markdown
    4. Paste this into a new file with the same name but the .md extension, and remove the old .html or .php file.

The style guide for code documentation and comments can be found in the Code Style Guide wiki.

Additional Notes

Issue and Pull Request Labels

This section lists the labels we use to help us track and manage issues and pull requests. These labels are used on the Keyman app repo and the website repos.

GitHub search makes it easy to use labels for finding groups of issues or pull requests you're interested in. The labels are loosely grouped by their purpose, but it's not required that every issue has a label from every group or that an issue can't have more than one label from the same group.

Type of Issue

Label name keyman 🔎 Description
auto search For PRs only: automatically-opened PRs, e.g. opened by CI.
bug search For issues only: confirmed bugs or reports that are very likely to be bugs. PRs use fix to mark a bug fix.
change search Minor change in functionality, but not new.
chore search Cleanup work, maintenance, without change in functionality.
docs search Relating to any type of documentation.
feat search Feature requests.
fix search For PRs only: a bug fix, corresponds to issue label bug.
question search Questions more than bug reports or feature requests (e.g. how do I do X). Usually better on the Keyman Community
refactor search Code reorganization and refactoring, without change in functionality.
spec search Issues which are specifications for a large scale feature.
style search Code formatting only.
test search Relating to automated tests.

Issue State

Label name keyman 🔎 Description
requires-design-work search Issues which need design before they can proceed.
help wanted search The Keyman core team would appreciate help from the community in resolving these issues.
good first issue search Less complex issues which would be good first issues to work on for users who want to contribute to Keyman.
duplicate search Issues which are duplicates of other issues, i.e. they have been reported before.
low-priority search The Keyman core team has decided not to fix these issues for now, but may in the future as time permits.
wontfix search The Keyman core team has decided not to fix these issues for now, either because they're working as intended or for some other reason.
invalid search Issues which aren't valid (e.g. user errors).
compatibility search Related to interactions with other applications.
dependencies search Related to changes in dependencies, often automatically generated.
external search Related to issues that require changes to third party applications in order to be resolved.

Platform and Feature Categories

These labels also include sublabels, such as windows/config/.

Label name keyman 🔎 Description
android/ search Related to Keyman running on Android.
common/ search Related to shared code.
core/ search Related to Keyman Core.
developer/ search Related to Keyman Developer.
ios/ search Related to Keyman running on iOS.
linux/ search Related to Keyman running on Linux.
mac/ search Related to Keyman running on macOS.
oem/ search Related to third party projects that are built together with Keyman.
web/ search Related to KeymanWeb.
windows/ search Related to Keyman running on Windows.

Pull Request Labels

Label name keyman 🔎 Description
cherry-pick search Pull requests which are essentially identical to another pull request, but for a different release version of Keyman.
refactor search Pull requests which include no functional changes but reorganise code.
user-test-missing search Pull requests where no user tests have been defined.
user-test-required search Pull requests where user testing is incomplete.