Morse Runner CE is a community-maintained project and we happily accept contributions. Thank you for your interest in Morse Runner and taking the time to contribute.
We are looking for the following types of people:
- Maintainers - Contributors who are responsible for driving the vision and managing the organizational aspects of the project. (requires collaborator permissions.)
- Contributors - Everyone who has contributed something back to the project. They might contribute to coding or testing, write documentation or develop training materials, etc.
- Community Members - People who use the project. They might be active in conversations or express their opinion on the project’s direction.
Please feel free to join in at whatever level you are comfortable.
The following is a set of guidelines for contributing to Morse Runner CE. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
This file will help people contribute to the project. It explains what types of contributions are needed and describes how the process works.
What should I know before I get started?
- Reporting Bugs
- Suggesting Enhancements
- Suggesting New Contests
- Your First Code Contribution
- Pull Requests
This project and everyone participating in it is governed by the Morse Runner Community Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected] or GitHub.
At this point, we do not yet have a general forum establish for Morse Runner. This will be added in the future. In the meantime:
- Before submitting a new Issue, search existing questions or feedback to see if a similar topic has already been discussed.
- Ask a general question or request support using the Question/Support template.
- Submit feedback using the Feedback template.
- As a community member, if you feel qualified to answer a question, please feel free to do so.
If you are new to open source software, please read How to Contribute to Open Source and other resources by Open Source Guides. See Additional Resources section below for additional information.
If you wish to fix a bug, add a new feature or contest, provide documentation, develop training materials, or help in any way, these steps will get you started.
The atom editor project has provided some good content. Their material applies to our project as well and has inspired much of our content.
This section guides you through submitting a bug report for Morse Runner.
Before submitting bug reports, please consider the following as you may find you don't need to create one.
- Check for existing issues 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.
- If you find a Closed issue that seems similar to the issue you are reporting, open a new issue and include a link to the original issue in the body of your new one.
- If you are available to help test an existing issue, please indicate by adding a comment to the issue.
Bugs are tracked as GitHub issues. When you create a bug report, please include as many details as possible. Please provide the following information by filling out the bug report template.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title.
- Describe the exact steps which reproduce the problem.
- Describe what Morse Runner mode you were running.
- Describe the behavior you observed.
- Explain the behavior you expected to see and why.
- Include screenshots if appropriate.
Provide more context by answering these questions:
- Did the problem start happening recently (e.g. after updating a new version) or was this always a problem?
- If the problem is recent, can you reproduce it in an older version? What's the most recent version in which the problem doesn't happen? You can download older versions from the releases page TBD.
- Can you reliably reproduce the issue? If not, provide details on about how often the problem happens or the conditions under which it happens.
Include details about your environment:
- Which version of Morse Runner are you using? You can get the version number from the Morse Runner About Box or the splash screen after program startup.
- What OS and version are you running?
Can you help?
- Are able to help the developer by answering questions or being available to test the solution once available?
This section guides you through an enhancement suggestion to Morse Runner, including complete new features or minor improvements to existing functionality.
Keep in mind the MR team has limited resources so it's unlikely that we'll work on every request.
We will however label these requests with the help wanted tag so other community members will see them.
If we're interested in a particular feature however, we'll follow up and ask you to discuss it in more detail.
Before creating enhancement suggestions, please consider the following as you may find you don't need to create one.
- Perform a search to see if the enhancement has already been suggested. Look for issues marked with the
enhancementlabel. - If it has, add a comment to the existing issue instead of opening a new one.
- If you are available to help test an existing issue, please indicate by adding a comment to the issue.
Enhancement suggestions are tracked as GitHub issues. Please provide the following information by filling in the feature request template.
Explain the feature request and describe why you think this feature is needed.
- Use a clear and descriptive title.
- Provide a step-by-step description of the suggested enhancement.
- Describe the current behavior and explain which behavior you expected to see and why.
- Include screenshots if appropriate.
- Explain why this enhancement would be useful to most Morse Runner users.
This section guides you through adding a contest request to Morse Runner.
We will add the contest label to each request; community members can volunteer to implement or help test each new contest. We have limited resources so it's possible that every request will not be implemented.
- Submitting a contest is similar to submitting a feature request.
Before submitting a new contest, please search contest requests to see if this contest has already been requested.
- If it has, please add a comment indicating your support for this contest. Contest requests are sorted by comment count. We use comment count as a proxy vote for each contest.
- If you are available to help testing, please add a comment to the request.
Contest support suggestions are tracked as GitHub issues. Please provide the following information by filling in the contest request template.
- Explain the contest request and describe why you think this contest is needed.
- Use a clear and descriptive title (e.g. Add Support for ARRL FD).
- Provide a link to the contest rules.
- Explain any special contest exchange behaviors that should be considered when adding this contest.
Unsure of where to begin with Morse Runner? You can start by looking through these good first issue and help wanted issues:
- Beginner issues - issues that will only require a few lines of code or perhaps some documentation changes.
- Help wanted issues - issues that are a bit more involved than
beginnerissues.
Both issue lists are sorted by number of comments. Number of comments serves as a proxy for the impact a given change will make.
To make changes to the code:
-
Select an issue you would like to work on. There is a good first issue label for issues that should be ideal for people who are new to the MorseRunner project and code base.
-
Change the issue state to "active" to indicate you are actively working on this issue.
-
Fork the repository and clone it locally. Connect your local to the original "upstream" repository by adding it as a remote. Pull in changes from "upstream" often so that you stay up to date so when you submit your pull request, merge conflicts will be less likely. (For more detailed instructions, see syncing a fork.)
-
Open a pull request to track the work associated with the issue you have selected. See Pull Requests below for more information. Reference the issue # on which you are working.
-
Create a branch for your changes. Please follow the additional developer guidelines below.
-
Contribute in the style of the project to the best of your abilities. This may mean using indents, semi-colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, and for others to understand and maintain in the future. See developer guidelines below for more information.
-
[future] Develop unit tests to exercise the new functionality. Some low-level code can be tested at the unit-test level.
-
Add a changelog entry and update Readme.txt as appropriate.
A pull request is used to track work being done within the project. When you start working on a specific issue, create a pull request and indicate which issue you are working on. Keep the PR update-to-date during your development to notify others of your progress. If a larger change, you can push your branch so others can have an early-look at your changes. When your work is complete, the PR will be submitted for review by one or more of the reviewers.
-
Reference any relevant issues or supporting documentation in your PR (for example, "Closes #13."). Usually a PR has an associated Issue #.
-
Include screen shots of the before and after if your change involves changes to the UI. Drag/drop the changes into your pull request.
-
Test your changes! Please test your changes to best extent possible as there is no formal test plan or test suite for this project. Consider asking the issue's author if they are available for early testing. If so, push your branch and let them test it.
-
Send the completed pull request when your work is complete. This notifies the maintainer of your pending contribution who will in turn merge and publish your changes. This may be an iterative process if others have found issues or have recommendations for additional changes.
- TODO - verify that this is how the process actually works.
This process presumes you have created a branch with your changes.
Your branch should be rooted of our main branch.
- To create a pull request start at the root of our repository.
- click
branches(next to the# branches). - Find your active branch and click
New pull request(on the right). - Now modify the comparison and repository settings. This is tricky, so get this right...
Change the base repository from
VE3NEA/MorseRunnertow7sst/MorseRunner. - Change the other fields to your branch name. If successful you should see
Able to Merge. - You can update your comment.
- Click
Create pull request. - On the left, add a reviewer.
As contributors, we should adopt reasonable open source development processes and conventions. As a starting point, we can draw from www.opensource.guide. These guidelines are recommendations, not rules. Please use your own judgment.
- TODO - identify other sources/examples of community development guidelines and best practices for open source projects.
- TODO - pull in examples and table of contents from atom project (see below)
-
Use feature branches. Each enhancement should be developed on a separate feature branch. Each branch can independently reviewed and tested before integration into main branch. The idea is to keep each feature small and independent. This is a common open source approach with multiple contributors and allows easy code review and integration by other community members and maintainers.
-
Open new issues. whenever new unrelated problems or bugs are found during development. Avoid going beyond the scope of the current problem when working on an issue.
-
Unit Testing. [future] When and where appropriate, develop unit tests to fully test low-level modules and if possible, show that a feature or behavior is working as expected. An example would be exercising the function that looks for a partial match of a user-entered string against a given callsign.
- TODO - develop unit test capability within Morse Runner.
-
Code reviews by other developers, project maintainers, and/or community members should be performed on the feature branch as part of submitting the pull request. Doing so will help maintain a solid code base. Reviews also serve as a good way to learn details of the project. Reviewers are looking for bugs and adherence to coding standards. Additional code changes are often made after a review to incorporate suggested improvement and/or suggestions. Some reviewers may even contribute specific code changes as part of the review. Code reviews will typically occur near the end of development or after submitting your PR (Pull Request) for review.
- TODO - We need to define how/when the code review occurs. Github has tools to facilitate code reviews. We need to find and adopt these tools and perhaps setup a automated processes if possible.
-
Code refactoring is encouraged and should always be performed independent of feature development or bug fixing. If working on a feature and you discover a refactoring opportunity, please do this refactoring using a separate feature branch before completing work on the current feature.
-
Avoid reformatting of existing code (e.g. changing indentation, if/then/else alignment, etc.). Doing so make it really hard to merge and compare code. a. When modifying existing code, following the coding style of the original author. a. When writing a new module/unit, following recommended coding guidelines. a. Short term, we may remove code reformatting to make it easier to compare/merge code as needed. a. Long term, after most branches have been merged, we can consider code reformatting.
-
Design Changes. Please discuss any design changes with the project maintainers before making these changes. If a pull request arrives without a prior discussion regarding design or direction changes, the request will probably be denied. We are open to design proposals and changes, but we do request that such changes are discussed early. Please open an Issue do we can let the design discussion occur and allow the design idea/proposal to evolve into something that we can agree to.
- TODO - define how/where changelog entries are managed. a. If fixing a bug, mention the fix in the changelog file. TODO - what file? a. If adding a new feature, mention the enhancement in the changelog file. a. If appropriate, summarize the feature in Readme.txt.
TODO...
TODO...
This section lists the labels we use to track and manage issues and pull requests.
GitHub search make it easy to use labels for finding groups of issues or pull requests you're interested in. For example, you might be interested in beginner issues or perhaps open pull requests which haven't been reviewed. To help you find issues and pull requests, each label is listed with a search link for finding open items with that label. See other search filters which will help you write more focused queries.
We will grow these labels over time as we better understand this process and how to use them. Please open an issue if you have suggestions for new labels.
| Label name | Search | Description |
|---|---|---|
bug |
search | Confirmed bugs or reports that are very likely to be bugs. |
documentation |
search | Related to any type of documentation. |
enhancement |
search | New feature or requests, including contest nominations. |
feedback |
search | General feedback; more than bug reports and feature requests. |
question |
search | Further information is requested. Questions that are more than bug reports or feature requests. |
training |
search | Related to any type of training or presentation material (e.g. club presentation). |
| Label name | Search | Description |
|---|---|---|
good first issue |
search | Less complex issues which would be good first issues to work on for users who wanted to contribute to MorseRunner. |
| Label name | Search | Description |
|---|---|---|
active |
search | Issues being actively worked on by a community member. |
blocked |
search | Issues blocked on other issues. |
confirmed |
search | Issues have been confirmed and ready to be fixed/implemented. |
duplicate |
search | This issue or pull request already exists. |
help wanted |
search | Extra attention is needed. The MorseRunner team would appreciate help from the community in resolving these issues. |
invalid |
search | Issues which aren't valid (e.g. user errors). |
more information needed |
search | Likely bugs, but haven't been reliably reproduced. |
someday maybe |
search | Issues/Ideas to be considered in the future. |
wontfix |
search | The MorseRunner reviewer team has decided not to fix these issues now, either because they're not working as intended or for some other reason. |
| Label name | Search | Description |
|---|---|---|
contest |
search | Related to behavior associated with a particular contest. |
crash |
search | Report of MR completely crashing. |
git |
search | Related to Git functionality (e.g. .gitignore files or showing correct file status) |
hst |
search | Related to High Speed Test (HST) mode, including posting high scores to internet. |
n1mm |
search | Related to N1MM integration |
ui |
search | Related to user interface or menus |
windows |
search | Related to MorseRunner running on Windows |
| Label name | Search | Description |
|---|---|---|
needs review |
search | Pull requests which need code review, and approval from maintainers. |
needs testing |
search | Pull requests which need manual testing. |
requires changes |
search | Pull requests which need to be updated based on review comments and then reviewed again. |
under review |
search | Pull requests being reviewed by maintainers. |
work in progress |
search | Pull requests which are still being worked on, more changes will follow. |
Initially, we have added lots of links here to get you started. We welcome any contributions or changes to this section - please submit a pull request if interested. Thank you! 🎉
TODO - write install, setup and compilation instructions.
The following resources are available to learn more about Open Source Software in general.
-
Open Source Guides - they publish several guidebooks on various aspects of Open Source Software development:
- How to Contribute to Open Source - good for those new to open source.
- Starting an Open Source Project - ideas and suggestions used to get this project off the ground.
- Finding Users for Your Project - how to grow your project.
- Building Welcoming Communities -
- and others.
-
GitHub Get Started - A good starting point to learn about git and GitHub.
-
GitHub Quickstart Guide - Using GitHub to manage Git repositories and collaborate with others. Provides an extensive overview of github and using git.
-
GitHub Flow - GitHub describes their common GitHub Flow for making changes, managing issues and pull requests. This project will follow this flow.
-
-
Github Skills - Learn how to use GitHub with interactive courses designed for beginners and experts.
-
Markdown Guide - Our documentation, including Issues and Pull Requests, is written using markdown syntax. This site describes the markdown syntax, including basic and extended syntax.
-
See also:
Project maintainers are given read/write access to the repository. The following articles will help you better understand this role.
-
Collaborator access for a repository owned by a personal account.
-
Best Practices for Maintainers - good for project leaders and maintainers of Morse Runner CE.
-
https://www.jeffgeerling.com/blog/2016/why-i-close-prs-oss-project-maintainer-notes
- https://docs.microsoft.com/en-us/contribute/
- https://urllib3.readthedocs.io/en/latest/contributing.html
- https://coda.io/@mahavir/working-with-multiple-forks - Ideas for working with multiple forks.
- https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
- https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
We'd like to "tip our hats" and say "Thank you!" and acknowledge the following projects for providing insight into starting and supporting our community-maintained open source project.
- https://opensource.guide
- https://github.com/atom/atom, https://github.com/atom/atom/blob/master/CONTRIBUTING.md
- https://mozillascience.github.io/working-open-workshop/contributing/ - How to build a contributing.md, including training for open source projects; includes nine presentations and handouts.
- https://urllib3.readthedocs.io/en/latest/contributing.html
Other good sources to pull ideas from: