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