Skip to main content...

W0CHP.radio

How to Contribute to the WPSD Project

So, you’d like to contribute to the WPSD project? Great! 👍 We welcome and embrace any contributions, and we’re excited that you’re interested!

Here’s what the project needs, and how you can get started…

Table of Contents:

WPSD Components/Sub-Projects

These are specific areas within project which can always use help and contributions:

  • Documentation
  • Code Contributions
  • Bug Reports
  • Translations (i18n / l10n)
  • Architecture/Porting
  • Advocacy, Evangelism & Education

How to Make or Submit Your Contributions

Some folks surprise us, and simply submit contributions without any notice - which is great!!! Additionally, some folks like to chat with us about their ideas/proposed contributions before they actually contribute, which is also fine. If you want to chat with us about your contributions, join our Discord Server and ask for access to our “#contributors” channel. Although WPSD has an official Facebook group, this medium is primarily used and promoted as a community user support resource only. If folks ask about contributions in our WPSD Facebook group, we will typically direct these people to the Discord server instead.

However you wish to proceed with your contributions, below is a list of areas within the WPSD project where contributions are needed the most…

Documentation

As WPSD has grown and continues to grow in popularity and usage, documentation is crucial; for both new and seasoned users. WPSD has a User Manual, but it is a “living” document and could always use updates and contributions. As of this writing (11/4/2023), it is incomplete, and needs lots of help. This will be WPSD’s official “handbook”, so-to-speak.

To contribute to the documentation project, head over to the User Manual source code, fork the repo, make your updates and submit Pull Requests!

Code / Programming

Code contributions affect how WPSD operates. We could always use help with these; as these can be bug fixes, optimizations, features, etc.

To get started contributing actual WPSD code, head over to the WPSD-Dev organization. Within that section, you will find all of the vital WPSD code repositories that make WPSD actually operate. Fork the code and submit your Pull Requests!

Be sure to check out any outstanding issues/bugs, as these are immediately available for contributors to help with!

Bug Reports

We always appreciate validated bug reports. However, beware that we receive many “bug reports”, which aren’t actually bugs at all. 😦 Instead, they are user errors, a lack of understanding from the user, support-oriented requests, and more. These can be frustrating for our core team, because we spend valuable time and effort chasing down a “bug” that doesn’t exist!

A valid bug report contains detailed instructions on how to reproduce the issue, and is commonly accompanied with ways to correct/fix/address the bug (code snippets, code patch files, etc.).

That said, there are times when we reject and close out bug reports, because we deem them as invalid, or when we may insist on a pull request instead. This is at our sole discretion.

Frankly, the best, fastest and most-appreciated way to address bugs, is to fix them yourself and to submit a pull request.

Translations (i18n / l10n)

Since WPSD is used by thousands of amateur radio operators around the globe, translations (i18n / l10n) are paramount. WPSD has some basic translation functionality built-in, but it is incomplete, and could use more help and optimization.

Currently, the translation files are located within the /lang/ folder in the Dashboard web code. Each language has its own dictionary/translation file (in PHP). The dictionary contains an array of key/value pairs, and the “key” is a variable called from several places within the rest of the Dashboard code. The appropriate language/translation file is chosen and set once a user selects their desired language from the main configuration page*.

These translation key variables need to be placed in more locations within the Dashboard code, as well as more translations added to the language files.

Note that we are not “married” to this method of translation. There are likely better ways to translate text in the Dashboard code, and we are always willing to accept improvements and new translation strategies (e.g. gettext, etc.).

* Auto-translation based on the user’s computer/browser locale would be really cool! 😄

Architecture/Porting

WPSD currently supports the popular Raspberry Pi architecture (Zero, 2, 3, 4, 5, etc.), as well as NanoPi Neo and OrangePi Zero. We are interested in providing disk images and functionality for other platforms and architectures, such as…

  • x86_64 platforms (with modem support by way of USB, such as the USB ZUMspot hotspot stick)
  • More NanoPi and OrangePi board models
  • Any other boards/architectures compatible with MMDVM modems via GPIO and/or USB facilities
  • Virtualized platforms with high-speed USB/serial read/write access for MMDVM modems

Additionally, the method of which the disk images are created, is somewhat crude, and is unfortunately, intimately tied to internal infrastructure. We would like this process to be a much more portable paradigm, where a full disk image can be created for any target, on any source machine. Think of a master disk image build script that can perform all necessary tasks to build these images, especially in an automated fashion if desired. Arguably, this method would need to be created/coded from scratch.

Advocacy, Evangelism and Education

This is an easy part of the WPSD project, and no special skills are required; anyone can do these things, and they are quite valuable!

Types of project advocacy & evangelism strategies include:

  • Telling your friends, family, colleagues about WPSD.
  • Writing, blogging, making videos or live streams about WPSD.
  • Showcasing / presenting WPSD at ham clubs, meetings, hamfests, etc.
  • Helping a fellow ham to install, learn and use WPSD.

Invariably, the more people who become aware and use WPSD, the more people that become available and willing to help contribute to the project as it garners additional interest. This means that the project can continue to improve and evolve even more! 🙏

Financial Contributions

Financial contributions are important; as building, hosting and testing WPSD all costs money. You can donate any amount you’re comfortable with by using the WPSD Project GoFundMe Campaign.

Disclaimers, Expectations, Guidelines and Notes

Code Contributions

If you’re interested in contributing actual code, pull requests, programming etc. to the project; please either already be familiar with git, repository forking, branching, merging, submitting pull requests and related code submission workflows - OR learn and master these strategies and techniques before attempting to contribute code to the WPSD project.

Our expectation, bluntly, is that you are already familiar and comfortable/proficient at these strategies/workflows, We cannot and will not train, educate or guide aspiring or would-be developers, or folks not familiar with the aforementioned techniques. We’re a small team with careers, families and many other obligations, so we need folks to hit the ground running out-of-the-gate. We are hopeful that you can understand this! 😄

Dev Team Access and Code Repository Merge / Push / Release Access

As stated in other places, the core WPSD development team is small, and select few have the ability to merge, push and publish pull requests, updates, releases etc. Additionally, these core dev team members also have access to our private WPSD Development Discord Server.

It is not a requirement nor mandatory that code contributors be core dev team members – we encourage, accept and embrace contributions from anyone! 😄 In fact, lots of contributions originate from others outside of our core team! 👍 However, there are some caveats with this, of course…

The core dev team are the folks who audit, discuss, QA, and have the ultimate final approval/rejection of code contributions. The core dev team are the core project decision-makers and project leaders/managers.

So if you contribute code and it is rejected by the team, please know there is a valid reason(s) for the rejection; so please don’t let this discourage you from contributing or continuing to contribute! 👍

With that caveat(s) out of the way, we still highly encourage code contributions, and we really need them! So you may be wondering how you can join the private WPSD Development Discord Server, or how you can become a core WPSD Dev Team member.

Here’s how it works…

WPSD development vision and strategy efforts, and WPSD core dev team-forming, operates in an informal meritocracy-basis. Someone who displays merit, is someone who is extremely proficient, motivated and prolific in improving the WPSD project. We notice these people, and if merited, we will typically invite them to be core dev. team members. Basically, this is typically an invite-only type of process, after internal core dev team members have discussed the proposition of inviting outstanding contributors to the WPSD project.

Document Version: a5745fb -- Last Revision: 11/10/2024
Permanent Link: <https://w0chp.radio/articles/how-to-contribute-to-wpsd/>