CONTRIBUTING.md

   1 MagickD Contributing Guide
   2 ==========================
   3
   4 Thank you for your interest in contributing to MagickD!
   5
   6 The goal for MagickD is to provide both low-level bindings
   7 (`graphicsmagick_c`) and a high-level interface (`magickd`) to the
   8 [GraphicsMagick] library.  Currently, `graphicsmagick_c` is a complete
   9 binding to GraphicsMagick version 1.3.0, meanwhile `magickd` is still
  10 in the early stages of development.
  11
  12 [GraphicsMagick]: http://www.graphicsmagick.org
  13
  14
  15 These are the main links that you'll need for contributing on MagickD:
  16
  17 * [Repository](https://codeberg.org/supercell/magickd)
  18 * [Issue Tracker](https://codeberg.org/supercell/magickd/issues)
  19
  20
  21
  22 Where to help
  23 -------------
  24
  25 > *I can't fly this ship alone.*
  26
  27 If you're computer runs macOS or Windows, then making sure MagickD works
  28 on your OS would be of immense help.  Otherwise, simply using the
  29 library and reporting any bugs that you encounter is also incredibly
  30 helpful.
  31
  32 Whist I've been trying to improve the documentation, you could also help
  33 by fleshing out areas that might still be a bit terse.
  34
  35
  36
  37 How to help
  38 -----------
  39
  40 ### Issue Reporting
  41
  42 > *Make sure you search existing issues so you don't create duplicates!
  43 > If you do create a duplicate issue, I **will** send you a bill for
  44 > [1 Million Dollars] in the mail.*
  45
  46 If you want to report a bug, first search [the issue tracker] for
  47 existing issues that describe your issues.
  48
  49 Can't find an existing issue? Then please create one! The ideal format
  50 currently is the following (copy, paste, and edit!)
  51
  52 ```md
  53 **Description**
  54
  55 `graphicsmagick_c` examples doesn't compile on Windows.
  56
  57 The bash scripts don't work on Windows due to $reason.
  58
  59 I tried doing X, Y, Z but they didn't work either.
  60
  61 **Version Information**
  62
  63 * Operating System: Windows 10
  64 * GraphicsMagick: 1.3.38
  65 * MagickD: 0.0.0 ;)
  66
  67 **Stack Trace**
  68
  69     object.Exception@onlineapp.d(5): Any one reading this?
  70     ----------------
  71     ./onlineapp.d:5 void onlineapp.throwException(immutable(char)[]) [0x55d8f8943def]
  72     ./onlineapp.d:10 void onlineapp.func() [0x55d8f8943e0b]
  73     ./onlineapp.d:14 _Dmain [0x55d8f8943e18]
  74 ```
  75
  76 If you're including a stack trace or snippets of code, please use the
  77 Markdown code block syntax. While I ask that you provide as much
  78 information as you can, don't worry too much much as I'll likely ask for
  79 more details anyway.
  80
  81 [the issue tracker]: https://codeberg.org/supercell/magickd/issues
  82 [1 Million Dollars]: https://www.youtube.com/watch?v=cKKHSAE1gIs
  83
  84 ### Environment Setup
  85
  86 > *After you've started your playlist of Amazarashi; procured some snacks
  87 > and water...*
  88
  89 Make sure you've installed a [D Compiler] and [dub] (note that DMD comes
  90 with dub).  You should also install GraphicsMagick to check your
  91 changes: http://www.graphicsmagick.org/README.html.
  92
  93 From there, you should fork the repository on Codeberg, *clone your
  94 fork*, and get to work!
  95
  96 [D Compiler]: https://dlang.org/download.html
  97 [dub]: https://dub.pm/
  98
  99 ### Code Style
 100
 101 > *"Did you know you need to wait 24 hours before reporting a missing
 102 > person?" That's bullshit. You needn't. Please pay attention.*
 103
 104 This project follows the [D Style] conventions, with a couple of
 105 differences:
 106
 107 * Braces are [K&R style].
 108 * Indentation is 3 spaces.
 109
 110 You should be able to run [dfmt] to fix any styling issues.
 111
 112 [dfmt]: https://github.com/dlang-community/dfmt
 113 [D Style]: https://dlang.org/dstyle.html
 114 [K&R style]: https://en.wikipedia.org/wiki/Indentation_style#K&R_style
 115
 116
 117 ### Testing your changes
 118
 119 > *beep...boop...beep... \*computer explodes\**
 120
 121 Unfortunately there are no unit tests as of yet, so I'm relying on you,
 122 the committer, to try your changes through the provided examples &mdash;
 123 creating a new example if need be.
 124
 125 When building the examples, make sure you specify which Quantum Depth
 126 your GraphicsMagick installation uses (Q8, Q16, or Q32).  You can find
 127 this out by running `gm version | head -n1`.
 128
 129 ### Sending pull requests
 130
 131 > *"clone your fork"? What about my spoon?*
 132
 133 All development happens on the [Codeberg repository], this includes
 134 issue tracking.
 135
 136 For the moment, the only real rules for sending a pull request is that
 137 you're targeting the `master` branch (this is where all development
 138 happens), and that your not creating excessive commits.
 139
 140 If your changes are made in relation to an issue, please reference this
 141 in extended commit message.  For example:
 142
 143 ```
 144 [examples] Migrate convert.d to new API
 145
 146 See Also: https://codeberg.org/supercell/issues/6
 147 ```
 148
 149
 150 [Codeberg repository]: https://codeberg.org/supercell/magickd
 151
 152 Parting Words
 153 -------------
 154
 155 > *It's the nature of things that matters, not it's form.*
 156
 157 If there are minor issues with your code (e.g. style, placement,
 158 comments, etc.), these will be fixed by myself.  I'd rather you solve
 159 the issue or implement your feature than worry too much about how to
 160 name a variable.