Table of Contents
Run into a problem?
If you're having trouble using or configuring Plover, you might get more eyes on your problem and more immediate help by reaching out to the whole community:
Start by searching the list of open issues.
If you can find an issue that's the same as yours:
- You might learn of a workaround from the discussion thread.
- You might be able to provide the crucial detail needed to reproduce and resolve the issue by adding a new comment with your details.
You can create a new issue.
We welcome pull requests, and the response time is usually less than a week.
If you need to ping the devteam for feedback on a discussion, you can mention @openstenoproject/developers to ping the whole team.
Issues that have been added to the milestone plover-next are already on the dev team's "hitlist", and they're probably already working on them.
Anything else is up for grabs! Please drop a comment on an issue you're starting work on, and push your work to your fork regularly, so that we don't duplicate effort.
If you want feedback on your work before it's complete,
open a pull request and include [WIP] at the start of your PR title.
Plover is not yet PEP8 compliant, but please use PEP8 in what you add and modify.
Prefer use of classes where possible, decoupling of UI and logic is very important.
Try to keep whitespace changes in a different commit.
Similarly, if you need to update the style of a file, do that independently of substantive changes to the code.
Please try to keep the number of commits as low as needed, where each commit represents a logical separation. If you write something and then rewrite it in a later commit and submit a PR, it creates history that the repository doesn't need. It's best to squash commits that don't contribute to understanding your code.
In terms of overall development approach, the contribution guidelines of the Swift project with regard to incremental development and commit messages are sound advice for your work on Plover, as well.
For concrete details of the recommended commit message text formatting, see A Note About Git Commit Messages.
New features must be tested, the test suite must pass and the code must be buildable for a PR to be considered. In the pull request message, try to declare why you made your change. If it fixes any issues, then use GitHub's "[fix #123]" magic phrase. Mention what platforms you've tested the code on.
If more testing is needed, the devteam will apply the needs-testing label.
Read on for more about labels and the review workflow.
The devteam use labels to coordinate work on Plover. GitHub permissions limit the ability to add permissions to members of the Open Steno Project organization; if you're not yet a member, you won't be able to apply or remove labels yourself.
PRs use very few labels. They are not tagged as to whether they are a bug fix or a new feature because usually the scope is pretty small and easy to understand.
- needs-testing: The PR exists but still needs to be tested and reviewed. This is basically a flag for developers that this is in the queue to be looked at.
- in-progress: A devteam member is either testing or reviewing the PR. This serves as a way to remove the "needs-testing" flag so that we don't duplicate effort by having multiple persons reviewing the same PR.
- ready-to-submit:
The review is finished, and all's well, but we're holding off on merging for
some reason.
- Please leave a comment stating why you're holding off merging and when you expect to merge if you apply this label to an issue.
- waiting-on-author:
The review is done for now, and some changes are needed before the PR can be
merged.
- Feedback comments will have been left on the PR and/or patches explaining the changes needed.
- blocked-awaiting-external:
This work cannot be merged until another event has occurred.
That event might be another issue getting resolved or another PR
getting merged first.
Either way, the labeled issue cannot continue being worked on until something
else happens first.
- Please leave a comment stating why you're holding off merging and when you expect to merge if you apply this label to an issue.
Issues are classified by priority: low, medium, high, or critical.
- Critical means that the current version of Plover is unusable and needs a rerelease.
- High means short term.
- Medium means that it's desirable for a decent amount of people, or that it's a trivial task so getting it done won't take too much effort so why not do it.
- Low priority is either for things that we don't plan to work on but want to keep around, or for things that are very big in scope.
Unlike PRs, issues are categorized as one of: Bug, feature-request, question, task, wishlist.
-
Bug is something wrong in the code. This label will be accompanied by another label to give its state:
- needs-discussion for clarification
- needs-testing to reproduce the bug (especially true of machine-specific problems that require special hardware)
- confirmed for bugs that have successfully been reproduced
-
A feature-request represents a request for new functionality to be added to Plover. These will be prioritized as described in the previous section.
- A wishlist issue is an accepted feature request that the Plover developers would like to implement. This is an excellent label for would-be contributors to review.
-
Task is something that needs to get done, like documentation, creating a testing environment, writing a contributing.md, making a release. Basically meta stuff around the Open Steno Project.
-
The duplicate tag is added to issues when closing them as duplicates.
-
The invalid tag is used when there's an issue that's not actually a problem, but maybe we want to keep it around as a note to clarify docs or something.