Skip to content

Latest commit

 

History

History
198 lines (154 loc) · 7.72 KB

CONTRIBUTING.md

File metadata and controls

198 lines (154 loc) · 7.72 KB

Table of Contents

Contributing to Plover

Reporting Issues

Run into a problem?

Ask for Help

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:

Search Open Issues

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.

Create a New Issue

You can create a new issue.

Contributing Code

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.

Picking an Issue

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.

Code Style

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.

Commit Style

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.

Review Workflow

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.

Labels

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.

Pull Request Review Flow

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.

Issue Priority

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.

Issue Category

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.