Murex is community project. We gratefully accept contributions
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 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 static site CMS.
Each generated markdown file has a footer with a link to the YAML file that it was generated from.
You can compile the markdown files by running go generate from the root of
the project directory:
go generate ./...
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 xxx_platform.mx where:
xxxrefers to the name of the integration_platformrefers to either:any(runs on every platform),posix(Linux or UNIX only) orlinux,darwin(macOS),freebsd,openbsd,netbsd,dragonfly(DragonflyBSD),solaris,plan9,windows.- The file extension most be
.mx.
Example files also exist in /integrations to help you get started.
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 the stuff that has been documented 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.
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 should 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: Murex is committed to excellent backwards compatibility
This document was generated from gen/root/CONTRIBUTING_doc.yaml.