github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/gen/root/CONTRIBUTING.inc.md (about)

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