spiegel-keyman/CONTRIBUTING.md
2025-04-29 11:15:55 +07:00

479 lines
23 KiB
Markdown

# Contributing to Keyman
(Keyman team members, see also the [onboarding](https://docs.google.com/document/d/1i6fBi9K38-LitcJZiRfAvRu1-7H0iQ_op5kxDMdhSec/edit?usp=sharing) doc)
⭐ 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](https://github.com/keymanapp) 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](https://github.com/atom/atom/blob/master/CONTRIBUTING.md).)
## Table Of Contents
[Code of Conduct](#code-of-conduct)
[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)
[What should I know before I get started?](#what-should-i-know-before-i-get-started)
* [Keyman, Keyboard Layouts and Lexical Models](#keyman-keyboard-layouts-and-lexical-models)
[How Can I Contribute?](#how-can-i-contribute)
* [Reporting Bugs](#reporting-bugs)
* [Suggesting Enhancements](#suggesting-enhancements)
* [Your First Code Contribution](#your-first-code-contribution)
* [Building Keyman](#building-keyman)
* [Localize Keyman](#localize-keyman)
* [Other Ways of Getting Involved](#other-ways-of-getting-involved)
[Style Guides](#style-guides)
* [Principles of Keyman Code Changes](#principles-of-keyman-code-changes)
* [Pull Request and Commit Workflow](#pull-request-and-commit-workflow)
* [Code Style Guide](#code-style-guide)
* [User Testing](#user-testing)
* [Documentation Style Guide](#documentation-style-guide)
[Additional Notes](#additional-notes)
* [Issue and Pull Request Labels](#issue-and-pull-request-labels)
## Code of Conduct
This project and everyone participating in it is governed by the [Keyman
Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected
to uphold this code. Please report unacceptable behavior to
[community@keyman.com](mailto:community@keyman.com).
## 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!
* [Keyman Community](https://community.software.sil.org/c/keyman)
## 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](https://github.com/keymanapp/keyman) monorepo, but
[keyboard layouts](https://github.com/keymanapp/keyboards) and [lexical
models](https://github.com/keymanapp/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:
* [Keyman app](https://github.com/keymanapp/keyman)
* [Keyboards](https://github.com/keymanapp/keyboards)
* [Lexical models](https://github.com/keymanapp/lexical-models)
* [keyman.com site](https://github.com/keymanapp/keyman.com)
* [help.keyman.com site](https://github.com/keymanapp/help.keyman.com)
* [keymanweb.com site](https://github.com/keymanapp/keymanweb.com)
* [api.keyman.com site](https://github.com/keymanapp/api.keyman.com)
## 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 :pencil:, reproduce the behavior :computer:
:computer:, and find related reports :mag_right:.
Before creating bug reports, please check [this
list](#before-submitting-a-bug-report) 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](#how-do-i-submit-a-good-bug-report). Fill out [the required
template](https://github.com/keymanapp/keyman/issues/new?assignees=&labels=bug&template=bug_report.md&title=bug%3A+);
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
* **Check that you are running the [latest
version](https://keyman.com/downloads).**
* **Check the [community](https://community.software.sil.org/c/keyman)**
for common questions and problems; search there to see if other people
have reported the issue and possible solutions.
* **Determine [which repository the problem should be reported
in](#keyman-keyboard-layouts-and-lexical-models)**.
* **Perform a [cursory
search](https://github.com/search?q=+is%3Aissue+user%3Akeymanapp+label%3Abug)**
to see if the problem has already been reported. If it has **and the
issue is still open**, add a comment to the existing issue instead of
opening a new one.
#### How Do I Submit A (Good) Bug Report?
Bugs are tracked as [GitHub
issues](https://guides.github.com/features/issues/). After you've
determined [which
repository](#keyman-keyboard-layouts-and-lexical-models) 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](https://github.com/keymanapp/keyman/blob/master/.github/ISSUE_TEMPLATE/bug_report.md?plain=1)
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](https://www.cockos.com/licecap/) to record GIFs on macOS and
Windows, and [this tool](https://github.com/colinkeenan/silentcast) or
[this tool](https://github.com/GNOME/byzanz) 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](https://keyman.com/downloads).
* **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 :pencil: and find related
suggestions :mag_right:.
Before creating enhancement suggestions, please check [this
list](#before-submitting-an-enhancement-suggestion) 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](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the
template](https://github.com/keymanapp/keyman/issues/new?assignees=&labels=feat&template=feature_request.md&title=feat%3A+),
including the steps that you imagine you would take if the feature
you're requesting existed.
#### Before Submitting An Enhancement Suggestion
* **Determine [which repository the enhancement should be suggested
in](#keyman-keyboard-layouts-and-lexical-models).**
* **Perform a [cursory
search](https://github.com/search?q=+is%3Aissue+user%3Akeymanapp+label%3Afeat)**
to see if the enhancement has already been suggested. If it has, add a
comment to the existing issue instead of opening a new one.
#### How Do I Submit A (Good) Enhancement Suggestion?
Enhancement suggestions are tracked as [GitHub
issues](https://guides.github.com/features/issues/). After you've
determined [which
repository](#keyman-keyboard-layouts-and-lexical-models) 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](https://help.github.com/articles/markdown-basics/#multiple-lines).
* **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](https://www.cockos.com/licecap/)
to record GIFs on macOS and Windows, and [this
tool](https://github.com/colinkeenan/silentcast) or [this
tool](https://github.com/GNOME/byzanz) 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](https://github.com/keymanapp/keyman/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
- issues which should only require a few lines of code, and a test or
two.
* [Help wanted
issues](https://github.com/keymanapp/keyman/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
- 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](./docs/build/index.md).
### Localize Keyman
We use CrowdIn to develop translations for the Keyman user interface.
* [Localize Keyman](https://translate.keyman.com/project/keyman)
[![Crowdin](https://badges.crowdin.net/keyman/localized.svg)](https://translate.keyman.com/project/keyman)
### Other Ways of Getting Involved
Even if you are not a coder, there are many other ways you can help with
the Keyman project:
* [Other Ways of Getting
Involved](https://keyman.com/about/get-involved)
## 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.
* [Principles of Keyman Code Changes
Wiki](https://github.com/keymanapp/keyman/wiki/Principles-of-Keyman-Code-Changes)
### 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:
* [Pull Request and Commit workflow
wiki](https://github.com/keymanapp/keyman/wiki/Pull-Request-and-Commit-workflow-notes)
### 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.
* [Code Style Guide
wiki](https://github.com/keymanapp/keyman/wiki/Keyman-Code-Style-Guide)
### 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:
* [User Testing
wiki](https://github.com/keymanapp/keyman/wiki/User-Testing-Workflows)
### Documentation Style Guide
This applies to user documentation found both on
[help.keyman.com](https://github.com/keymanapp/help.keyman.com) and the
application user documentation found in the [Keyman
repository](https://github.com/keymanapp/keyman). 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](https://daringfireball.net/projects/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](https://www.browserling.com/tools/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](https://github.com/keymanapp/keyman/wiki/Keyman-Code-Style-Guide).
## 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](#keyman-keyboard-layouts-and-lexical-models).
[GitHub search](https://help.github.com/articles/searching-issues/)
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` :mag_right: | Description |
| --- | --- | --- |
| `auto` | [search][search-auto] | For PRs only: automatically-opened PRs, e.g. opened by CI. |
| `bug` | [search][search-bug] | For issues only: confirmed bugs or reports that are very likely to be bugs. PRs use `fix` to mark a bug fix. |
| `change` | [search][search-change] | Minor change in functionality, but not new. |
| `chore` | [search][search-chore] | Cleanup work, without change in functionality. |
| `docs` | [search][search-docs] | Relating to any type of documentation. |
| `feat` | [search][search-feat] | Feature requests. |
| `fix` | [search][search-fix] | For PRs only: a bug fix, corresponds to issue label `bug`. |
| `maint` | [search][search-maint] | Maintenance work -- continuous integration, build scripts, infrastructure. |
| `question` | [search][search-question] | Questions more than bug reports or feature requests (e.g. how do I do X). [**Usually better on the Keyman Community**](https://community.software.sil.org/c/keyman) |
| `refactor` | [search][search-refactor] | Code reorganization and refactoring, without change in functionality. |
| `spec` | [search][search-spec] | Issues which are specifications for a large scale feature. |
| `style` | [search][search-style] | Code formatting only. |
| `test` | [search][search-test] | Relating to automated tests. |
#### Issue State
| Label name | `keyman` :mag_right: | Description |
| --- | --- | --- |
| `requires-design-work` | [search][search-requires-design-work] | Issues which need design before they can proceed. |
| `help wanted` | [search][search-help-wanted] | The Keyman core team would appreciate help from the community in resolving these issues. |
| `good first issue` | [search][search-good-first-issue] | Less complex issues which would be good first issues to work on for users who want to contribute to Keyman. |
| `duplicate` | [search][search-duplicate] | Issues which are duplicates of other issues, i.e. they have been reported before. |
| `low-priority` | [search][search-low-priority] | The Keyman core team has decided not to fix these issues for now, but may in the future as time permits. |
| `wontfix` | [search][search-wontfix] | 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][search-invalid] | Issues which aren't valid (e.g. user errors). |
| `compatibility` | [search][search-compatibility] | Related to interactions with other applications. |
| `dependencies` | [search][search-dependencies] | Related to changes in dependencies, often automatically generated. |
| `external` | [search][search-external] | 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` :mag_right: | Description |
| --- | --- | --- |
| `android/` | [search][search-android] | Related to Keyman running on Android. |
| `common/` | [search][search-common] | Related to shared code. |
| `core/` | [search][search-core] | Related to Keyman Core. |
| `developer/` | [search][search-developer] | Related to Keyman Developer. |
| `ios/` | [search][search-ios] | Related to Keyman running on iOS. |
| `linux/` | [search][search-linux] | Related to Keyman running on Linux. |
| `mac/` | [search][search-mac] | Related to Keyman running on macOS. |
| `oem/` | [search][search-oem] | Related to third party projects that are built together with Keyman. |
| `web/` | [search][search-web] | Related to KeymanWeb. |
| `windows/` | [search][search-windows] | Related to Keyman running on Windows. |
#### Pull Request Labels
| Label name | `keyman` :mag_right: | Description |
| --- | --- | --- |
| `cherry-pick` | [search][search-cherry-pick] | Pull requests which are essentially identical to another pull request, but for a different release version of Keyman. |
| `refactor` | [search][search-refactor] | Pull requests which include no functional changes but reorganise code. |
| `user-test-missing` | [search][search-user-test-missing] | Pull requests where no user tests have been defined. |
| `user-test-required` | [search][search-user-test-required] | Pull requests where user testing is incomplete. |
[search-auto]: https://github.com/keymanapp/keyman/labels/auto
[search-bug]: https://github.com/keymanapp/keyman/labels/bug
[search-change]: https://github.com/keymanapp/keyman/labels/change
[search-chore]: https://github.com/keymanapp/keyman/labels/chore
[search-docs]: https://github.com/keymanapp/keyman/labels/docs
[search-feat]: https://github.com/keymanapp/keyman/labels/feat
[search-fix]: https://github.com/keymanapp/keyman/labels/fix
[search-maint]: https://github.com/keymanapp/keyman/labels/maint
[search-question]: https://github.com/keymanapp/keyman/labels/question
[search-spec]: https://github.com/keymanapp/keyman/labels/spec
[search-style]: https://github.com/keymanapp/keyman/labels/style
[search-test]: https://github.com/keymanapp/keyman/labels/test
[search-requires-design-work]: https://github.com/keymanapp/keyman/labels/requires-design-work
[search-help-wanted]: https://github.com/keymanapp/keyman/labels/help%20wanted
[search-good-first-issue]: https://github.com/keymanapp/keyman/labels/good%20first%20issue
[search-duplicate]: https://github.com/keymanapp/keyman/labels/duplicate
[search-low-priority]: https://github.com/keymanapp/keyman/labels/low-priority
[search-wontfix]: https://github.com/keymanapp/keyman/labels/wontfix
[search-invalid]: https://github.com/keymanapp/keyman/labels/invalid
[search-compatibility]: https://github.com/keymanapp/keyman/labels/compatibility
[search-dependencies]: https://github.com/keymanapp/keyman/labels/dependencies
[search-external]: https://github.com/keymanapp/keyman/labels/external
[search-android]: https://github.com/keymanapp/keyman/labels/android%2F
[search-common]: https://github.com/keymanapp/keyman/labels/common%2F
[search-core]: https://github.com/keymanapp/keyman/labels/core%2F
[search-developer]: https://github.com/keymanapp/keyman/labels/developer%2F
[search-ios]: https://github.com/keymanapp/keyman/labels/ios%2F
[search-linux]: https://github.com/keymanapp/keyman/labels/linux%2F
[search-mac]: https://github.com/keymanapp/keyman/labels/mac%2F
[search-oem]: https://github.com/keymanapp/keyman/labels/oem%2F
[search-web]: https://github.com/keymanapp/keyman/labels/web%2F
[search-windows]: https://github.com/keymanapp/keyman/labels/windows%2F
[search-cherry-pick]: https://github.com/keymanapp/keyman/labels/cherry-pick
[search-refactor]: https://github.com/keymanapp/keyman/labels/refactor
[search-user-test-missing]: https://github.com/keymanapp/keyman/labels/user-test-missing
[search-user-test-required]: https://github.com/keymanapp/keyman/labels/user-test-required