Contributing to Murex
Murex is community project. We gratefully accept contributions.
Ways To Contribute
You don't have to be a software developer to support this project, there are multiple ways you can contribute to Murex. Listed below are some examples of areas we are looking for support:
Writing or Updating Documentation
Writing documentation is probably the dullest part of any project yet arguably one of the most important. The vast majority of the documentation for Murex has been knocked out in a hurry by one guy - a guy who's core weaknesses might include "writing". So there is a considerable room for improvement to be made.
You don't even have to write any documentation from scratch. If you notice a grammatical error, spelling mistakes or even just a confusing sentence, then please do raise a pull request.
All documentation is written in markdown. Even the website is HTML generated from the original markdown documents. And all markdown documents are themselves generated from files with the extension
_doc.yaml. These template files are the backbone of the documentation's pseudo-CMS.
If you are unsure where to find a document, you can either
grep the source repository for a known phrase, or ask in the Github discussions group.
Murex is a smart shell - it parses man pages for command line flags. This helps to reduce the impact of missing custom autocompletions. However sometimes it is in escapable to need a custom completion. Maybe that is because the options are atypical (like how
kill should list PIDs with their application adjacent). Sometimes it might be because other integrations are required, such as events, aliases or functions defined.
One of the core tenets of Murex is that it's out-of-the-box experience should already be excellent and any customization that happens after is for personalization rather than because the default experience is lacking in some way. So Murex has made it very easy for you to contribute.
In the root of the project resides the integrations directory. Each file in there is compiled into Murex, assuming the following condition is met.
The file must be named
xxxrefers to the name of the integration
_platformrefers to either:
any(runs on every platform),
posix(Linux or UNIX only) or
- The file extension most be
Example files also exist in
/integrations to help you get started.
Raising Bug Reports or Feature Requests
It might seem counterintuitive that raising issues is a form of contribution but without feedback Murex cannot provide the out-of-box experience it aims to. So bug reports and feature requests do help.
These can be raised on our Github issue tracker.
Murex is written in a language called Go. Not a lot of Murex's code is well documented however that was is document can be found in the API section of the user guide.
If you want to share some shell tips, be it for Murex or any of the more traditional shells like Bash, then we welcome them as short articles for the blog section. We want the website to be a valuable resource for shells and scripting regardless for the platform and language.
Articles must be in markdown format and credit will be attributed with links to your Github account, Twitter or other social platforms and/or promotions.
Rasing Pull Requests
Pull requests should be raised against the
develop branch. This allows us to stage and test changes before releasing them to everyone.
Murex is a community project and as such, everyone is entitled to an opinion and opinions might differ. With that in mind, please be patient if discussions happen regarding your contributions. All contributions are welcome however we do also need to ensure that Murex has focus and a consistent design. This means sometimes a conversation might be needed to work that contribution into the wider, holistic, design of the shell.
This need not put anyone off contributing. However if you are unsure about whether a contribution fits, then you're welcome to start a discussion first.
By contributing, you agree to license your code under the same license as the existing source code (see the LICENSE file) and that @lmorg has the right to relicense Murex under an alternative open source license in the, future should the need arise.
Murex will always be open source software. It wouldn't exist without open source tooling and therefore it will always serve to enhance the open source community.
- Compatibility Commitment: Hack confidence in our backwards compatibility
This document was generated from gen/root/CONTRIBUTING_doc.yaml.