Commit: 44b75a04cc18306390ae0e11d32e40cd7b4a3387 - magickd (git)

D bindings to the GraphicsMagick library.

Commit MetaInfo

• Revisão: 44b75a04cc18306390ae0e11d32e40cd7b4a3387 (tree)
• Hora: 2023-07-16 15:54:25
• Autor: Mio <stigma@disr...>
• Commiter: Mio

Mensagem de Log

[docs] Rewrite CONTRIBUTING.md

Now uses Markdown and provides more of a walk-through.

Mudança Sumário

• modified: CONTRIBUTING.md

Diff

--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,79 +1,160 @@
 MagickD Contributing Guide
 ==========================
 
-1. Issues
-2. git Workflow
+Thank you for your interest in contributing to MagickD!
 
+The goal for MagickD is to provide both low-level bindings
+(`graphicsmagick_c`) and a high-level interface (`magickd`) to the 
+[GraphicsMagick] library.  Currently, `graphicsmagick_c` is a complete
+binding to GraphicsMagick version 1.3.0, meanwhile `magickd` is still
+in the early stages of development.
 
-Issues
-------
+[GraphicsMagick]: http://www.graphicsmagick.org
 
-Currently the bindings are incomplete, however, slow progress is gradually being
-made to complete them.  Because of this, bug testing isn't extensive.  If you do
-encounter a bug, or just want some binding completed quickly, you can just send
-me an email.  You don't have to fill out much, just a short description.
-Consider the following a template:
 
-	 [A paragraph or so about what the issue generally is.]
+These are the main links that you'll need for contributing on MagickD:
 
-	 OS Type (GNU/Linux, OSX, etc.) and version(s):
+* [Repository](https://codeberg.org/supercell/magickd)
+* [Issue Tracker](https://codeberg.org/supercell/magickd/issues)
 
-	    The operating system(s) and their version(s) that you encounter
-	    this issue on.
 
-	 magickd version(s):
 
-	    The magickd version(s) that you encounter the issue with.  You don't
-	    have to test every version, just the version you're currently using
-	    and perhaps the latest (if your not currently using it).
+Where to help
+-------------
 
-	 GraphicsMagick version(s):
+> *I can't fly this ship alone.*
 
-	    The GraphicsMagick version(s) that you encounter the issue with.
-	    Again, you don't have to extensively test different versions. Please be
-		aware that only version 3 and above are supported.
+If you're computer runs macOS or Windows, then making sure MagickD works
+on your OS would be of immense help.  Otherwise, simply using the
+library and reporting any bugs that you encounter is also incredibly
+helpful.
 
-	 Steps to reproduce:
+Whist I've been trying to improve the documentation, you could also help
+by fleshing out areas that might still be a bit terse.
 
-	    Perhaps the most important part, how can I encouter the same issue?
-	    If it's an issue with a particular image, you can send that as
-	    an attachment (so long as I have permission to use it as a public
-	    test case).
 
 
-Publicly tracked issues are currently available in the "Ticket" submenu on the
-OSDN page <https://osdn.net/users/nemophila/pf/magickd/ticket/>
+How to help
+-----------
 
+### Issue Reporting
 
-git Workflow
-------------
+> *Make sure you search existing issues so you don't create duplicates!
+> If you do create a duplicate issue, I **will** send you a bill for
+> [1 Million Dollars] in the mail.*
 
-There are two primary repositories for magickd:
+If you want to report a bug, first search [the issue tracker] for
+existing issues that describe your issues.
 
-* repo.or.cz:     https://repo.or.cz/magickd.git
-* OSDN.net:       https://osdn.net/users/nemophila/pf/magickd/
+Can't find an existing issue? Then please create one! The ideal format
+currently is the following (copy, paste, and edit!)
 
-Along with two mirrors:
+```md
+**Description**
 
-* rocketgit.com:  https://rocketgit.com/user/dawning/magickd
-* codeberg.org:   https://codeberg.org/supercell/magickd
+`graphicsmagick_c` examples doesn't compile on Windows.
 
+The bash scripts don't work on Windows due to $reason.
 
-For now, the preferred way of sending your contributions is via email.  My email
-address is located on all those sites, or you can find it in the git log.
+I tried doing X, Y, Z but they didn't work either.
 
-Alternatively, if you don't want to send an email, the rocketgit repo supports
-"anonymous push", this means you can create your git commits, push to the repo
-repo and a merge request is automatically created.  The basic workflow for this
-is as follows:
+**Version Information**
 
-      > git clone git://git.rocketgit.com/user/dawning/magickd
-      > cd magickd
-      # edit some files
-      > git add -p
-      > git commit -m $commit_message
-      > git push origin master
+* Operating System: Windows 10
+* GraphicsMagick: 1.3.38
+* MagickD: 0.0.0 ;)
 
-You should be prompted for a username and password. The username is "guest", and
-leave the passwork empty.  Finally, please don't use "$commit_message" for the
-commit message, write something that's actually useful.
+**Stack Trace**
+
+    object.Exception@onlineapp.d(5): Any one reading this?
+    ----------------
+    ./onlineapp.d:5 void onlineapp.throwException(immutable(char)[]) [0x55d8f8943def]
+    ./onlineapp.d:10 void onlineapp.func() [0x55d8f8943e0b]
+    ./onlineapp.d:14 _Dmain [0x55d8f8943e18]
+```
+
+If you're including a stack trace or snippets of code, please use the
+Markdown code block syntax. While I ask that you provide as much
+information as you can, don't worry too much much as I'll likely ask for
+more details anyway.
+
+[the issue tracker]: https://codeberg.org/supercell/magickd/issues
+[1 Million Dollars]: https://www.youtube.com/watch?v=cKKHSAE1gIs
+
+### Environment Setup
+
+> *After you've started your playlist of Amazarashi; procured some snacks
+> and water...*
+
+Make sure you've installed a [D Compiler] and [dub] (note that DMD comes
+with dub).  You should also install GraphicsMagick to check your
+changes: http://www.graphicsmagick.org/README.html.
+
+From there, you should fork the repository on Codeberg, *clone your
+fork*, and get to work!
+
+[D Compiler]: https://dlang.org/download.html
+[dub]: https://dub.pm/
+
+### Code Style
+
+> *"Did you know you need to wait 24 hours before reporting a missing
+> person?" That's bullshit. You needn't. Please pay attention.*
+
+This project follows the [D Style] conventions, with a couple of
+differences:
+
+* Braces are [K&R style].
+* Indentation is 3 spaces.
+
+You should be able to run [dfmt] to fix any styling issues.
+
+[dfmt]: https://github.com/dlang-community/dfmt
+[D Style]: https://dlang.org/dstyle.html
+[K&R style]: https://en.wikipedia.org/wiki/Indentation_style#K&R_style
+
+
+### Testing your changes
+
+> *beep...boop...beep... \*computer explodes\**
+
+Unfortunately there are no unit tests as of yet, so I'm relying on you,
+the committer, to try your changes through the provided examples &mdash;
+creating a new example if need be.
+
+When building the examples, make sure you specify which Quantum Depth
+your GraphicsMagick installation uses (Q8, Q16, or Q32).  You can find
+this out by running `gm version | head -n1`.
+
+### Sending pull requests
+
+> *"clone your fork"? What about my spoon?*
+
+All development happens on the [Codeberg repository], this includes
+issue tracking.
+
+For the moment, the only real rules for sending a pull request is that
+you're targeting the `master` branch (this is where all development
+happens), and that your not creating excessive commits.
+
+If your changes are made in relation to an issue, please reference this
+in extended commit message.  For example:
+
+```
+[examples] Migrate convert.d to new API
+
+See Also: https://codeberg.org/supercell/issues/6
+```
+
+
+[Codeberg repository]: https://codeberg.org/supercell/magickd
+
+Parting Words
+-------------
+
+> *It's the nature of things that matters, not it's form.*
+
+If there are minor issues with your code (e.g. style, placement,
+comments, etc.), these will be fixed by myself.  I'd rather you solve
+the issue or implement your feature than worry too much about how to
+name a variable.