How To Contribute

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 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 ./...

Writing Integrations

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:

• xxx refers to the name of the integration
• _platform refers to either: any (runs on every platform), posix (Linux or UNIX only) or linux, 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.

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.

Committing Code

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.

Blogging

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.

Raising Pull Requests

Pull requests should be raised against the develop branch. This allows us to stage and test changes before releasing them to everyone.

Etiquette

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.

Licensing

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.

See Also

• Compatibility Commitment: Murex is committed to excellent backwards compatibility

---

This document was generated from gen/root/CONTRIBUTING_doc.yaml.