github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/CONTRIBUTING.md (about) 1 <h1>Contributing to Murex</h1> 2 3 Murex is community project. We gratefully accept contributions. 4 5 <h2>Table of Contents</h2> 6 7 <div id="toc"> 8 9 - [Ways To Contribute](#ways-to-contribute) 10 - [Writing or Updating Documentation](#writing-or-updating-documentation) 11 - [Writing Integrations](#writing-integrations) 12 - [Raising Bug Reports or Feature Requests](#raising-bug-reports-or-feature-requests) 13 - [Committing Code](#committing-code) 14 - [Blogging](#blogging) 15 - [Raising Pull Requests](#raising-pull-requests) 16 - [Etiquette](#etiquette) 17 - [Licensing](#licensing) 18 19 </div> 20 21 ## Ways To Contribute 22 23 You don't have to be a software developer to support this project, there are 24 multiple ways you can contribute to Murex. Listed below are some examples of 25 areas we are looking for support: 26 27 ### Writing or Updating Documentation 28 29 Writing documentation is probably the dullest part of any project yet arguably 30 one of the most important. The vast majority of the documentation for Murex 31 has been knocked out in a hurry by one guy - a guy who's core weaknesses might 32 include "writing". So there is a considerable room for improvement to be made. 33 34 You don't even have to write any documentation from scratch. If you notice a 35 grammatical error, spelling mistakes or even just a confusing sentence, then 36 please do raise a pull request. 37 38 All documentation is written in markdown. Even the website is HTML generated 39 from the original markdown documents. And all markdown documents are themselves 40 generated from files with the extension `_doc.yaml`. These template files are 41 the backbone of the documentation's pseudo-CMS. 42 43 If you are unsure where to find a document, you can either `grep` the source 44 repository for a known phrase, or ask in the [Github discussions](https://github.com/lmorg/murex/discussions) 45 group. 46 47 ### Writing Integrations 48 49 Murex is a smart shell - it parses man pages for command line flags. This helps 50 to reduce the impact of missing custom autocompletions. However sometimes it is 51 in escapable to need a custom completion. Maybe that is because the options are 52 atypical (like how `kill` should list PIDs with their application adjacent). 53 Sometimes it might be because other integrations are required, such as events, 54 aliases or functions defined. 55 56 One of the core tenets of Murex is that it's out-of-the-box experience should 57 already be excellent and any customization that happens after is for 58 personalization rather than because the default experience is lacking in some 59 way. So Murex has made it very easy for you to contribute. 60 61 In the root of the project resides the [integrations directory](https://github.com/lmorg/murex/tree/master/integrations). 62 Each file in there is compiled into Murex, assuming the following condition is 63 met. 64 65 The file must be named `xxx_platform.mx` where: 66 67 * `xxx` refers to the name of the integration 68 * `_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`. 69 * The file extension most be `.mx`. 70 71 Example files also exist in `/integrations` to help you get started. 72 73 ### Raising Bug Reports or Feature Requests 74 75 It might seem counterintuitive that raising issues is a form of contribution 76 but without feedback Murex cannot provide the out-of-box experience it aims to. 77 So bug reports and feature requests do help. 78 79 These can be raised on our [Github issue tracker](github.com/lmorg/murex/issues). 80 81 ### Committing Code 82 83 Murex is written in a language called Go. Not a lot of Murex's code is well 84 documented however that was is document can be found in the [API section](/docs/apis) of the 85 user guide. 86 87 ### Blogging 88 89 If you want to share some shell tips, be it for Murex or any of the more 90 traditional shells like Bash, then we welcome them as short articles for the 91 [blog section](/docs/blog). We want the website to be a 92 valuable resource for shells and scripting regardless for the platform and 93 language. 94 95 Articles must be in markdown format and credit will be attributed with links to 96 your Github account, Twitter or other social platforms and/or promotions. 97 98 ## Raising Pull Requests 99 100 Pull requests should be raised against the `develop` branch. This allows us to 101 stage and test changes before releasing them to everyone. 102 103 ## Etiquette 104 105 Murex is a community project and as such, everyone is entitled to an opinion 106 and opinions might differ. With that in mind, please be patient if discussions 107 happen regarding your contributions. All contributions are welcome however we 108 do also need to ensure that Murex has focus and a consistent design. This means 109 sometimes a conversation might be needed to work that contribution into the 110 wider, holistic, design of the shell. 111 112 This should not put anyone off contributing. However if you are unsure about 113 whether a contribution fits, then you're welcome to [start a discussion ](https://github.com/lmorg/murex/discussions) first. 114 115 ## Licensing 116 117 By contributing, you agree to license your code under the same license as the 118 existing source code (see the [LICENSE](https://github.com/lmorg/murex/blob/master/LICENSE) file) and that @lmorg has the 119 right to relicense Murex under an alternative _open source_ license in the, 120 future should the need arise. 121 122 Murex will always be open source software. It wouldn't exist without open 123 source tooling and therefore it will always serve to enhance the open source 124 community. 125 126 ## See Also 127 128 * [Compatibility Commitment](/compatibility.md): 129 Hack confidence in our backwards compatibility 130 131 <hr/> 132 133 This document was generated from [gen/root/CONTRIBUTING_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/root/CONTRIBUTING_doc.yaml).