:hide-uri-scheme:
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
:toc:

:rnrh-test-folder: https://github.com/meliorence/react-native-render-html/tree/master/packages/render-html/src/__tests__

= A Contributors' Guide

[NOTE]
If you're starting to read this guide, well thanks for willing to contribute to
this project! Your effort will be very much appreciated.
*If you need help*, take a look at <<HELP.adoc#,our dedicated document>>.

[[tickets]]
== Opening Tickets

After you've read the relevant sections of this document, you can open a ticket
through GitHub here:
https://github.com/meliorence/react-native-render-html/issues/new/choose. Make
sure you follow the appropriate template.

[NOTE]
The art of filling good reports is as important and valued as the art of
producing readable, maintainable code. Developers tend to rush when filling
reports because their initiative stems from a place of frustration. This is
very well understandable, but ineffective regarding the goal of solving one's
problem. Consider the __time investment / benefits__ ratio: by filling a detailed
bug report, you might have committed a chunk of your
valuable time. But **your chances of having a fix merged rapidly have considerably
increased**.

[WARNING]
By not following our guidelines and templates, you risk having your ticket
closed without notice. Sorry about that... our time is also valuable, and we
cannot help you if you don't help us in the process!

=== Submitting a Bug

[CAUTION]
If you would like to report a problem, take a look around and see if someone
already opened an issue about it (see <<HELP.adoc#,HELP>> document). If you a
are certain this is a new, unreported bug, you can submit a bug report
https://github.com/meliorence/react-native-render-html/issues/new/choose[by
opening a new issue].

The most important quality of your bug report is *reproducibility*. It means we
can easily reproduce and investigate the bug to fix it as quickly as possible.
If you've never heard of a “minimal reproducible example”, take a look at this
guide: https://stackoverflow.com/help/mcve. Bellow is a table of different
types of reproductions:

[TIP]
If you add screencasts, screenshots, debugging information, or any insights
that can help us identify the failure as quickly as possible, you can consider
each a bonus :zap:.

[cols=3*,options=header,frame=topbot]
|===
|Reproduction
|Efficiency
|Information

|Regression Test
|:zap::zap::zap::zap:
|Offering a PR with a Test which reproduces the issue is the most efficient way
to have your bug fixed rapidly. More details on the *<<bug-repro,dedicated
section>>*. You are still required to open a bug report ticket, but you will be able
to skip many steps.

|Snack
|:zap::zap::zap:
|A *Snack* is very convenient for you and for us. You can
https://snack.expo.io/@jsamr/rnrhtml-template[*start from
our template*]. *Make sure you set the appropriate version of this library.*

|Git
|:zap::zap::zap:
|A Git reproduction is as efficient as a Snack, albeit it might be a little
extra work for you.

|Code Snippet
|:zap:
|A snippet is better than nothing, but we don't consider it __high quality__
and might take more time to investigate. Please consider put your snippet into
a *Snack*. I will take you 2 minutes to configure.
|===

Second important thing: try-out the latest version, including pre-releases! For
more information on this topic, read the
https://github.com/meliorence/react-native-render-html#versions[Versions section
of the README]. If you can try `master` branch, that would be even better, but
we don't require it because it could contain breaking changes. To do
so, simply run the following command:

```bash
npm install "github:meliorence/react-native-render-html#master"
```

[[features]]
=== Proposing a Feature or Enhancement

* Feature requests and enhancements **must** be submitted https://native-html.canny.io/features[in our Canny feature tracker].
* You can, *in addition*, consider <<rfc,writing an RFC>> and offering it as a PR.

[TIP]
You or your company need a feature? Consider https://github.com/sponsors/jsamr[sponsorship or consultancy] and it will be delivered ASAP.

== Pull Requests

[NOTE]
We require some criterion to accept a pull request. But don't worry, we're also
willing to help. You're encouraged to start a
https://github.blog/2019-02-14-introducing-draft-pull-requests/[Github draft]
and we will be glad to help you build it and make it comply with our
requirements. If you have any question or need advise regarding your
contribution, you can also ping us in our https://discord.gg/MwrZmBb[Discord
#contributing channel].

=== Bug Fixes

If your PR fixes a bug, you are required to implement a regression test to
prove your fix is effective, but *don't worry, we will help you*. The simplest
way is to look at {rnrh-test-folder}[our test folder] and copy/paste an existing __regression
test__ to get inspiration. You are also advised to read our <<DEVELOPING.adoc#, developing guide>>. If you know what the test should do, but don't
know how to implement the test, you can add a "Testing Plan" section in the
body of your PR.


[[bug-repro]]
=== Bug Reproduction

When you submit a bug ticket, the fastest path for us to resolve the issue is
by providing a bug reproduction. Take a glance at {rnrh-test-folder}[our test folder] and get
inspiration by looking at __regression tests__. You are also advised to read our <<DEVELOPING.adoc#, developing guide>>. The PR is ready __when the
test fails__.

=== Features

[NOTE]
We recommend you use the
https://github.blog/2019-02-14-introducing-draft-pull-requests/[draft Github option]
when you start a Feature PR!

If your PR provides new features, it means that the API of this library will
likely change. You will be required to test the new
feature.  Take a look at {rnrh-test-folder}[our test folder]. You are also advised to read our <<DEVELOPING.adoc#, developing guide>>. If you're lost, we will be glad to help you, either on
discord or within the PR on GitHub.


[[rfc]]
=== Request For Comments

[NOTE]
RFC are propositions for new methods, behaviors and other API capabilities, or
the exploration of an algorithmic challenge that is specific to this library.
These are not Internet Society's RFCs! We don't have a rich multi-stage process. An
RFC is either a draft, in discussion, or adopted (merged). We thereafter use
versioning to polish and enhance those specifications.

RFC purpose is to offer drafts for new ideas which goes relatively in depth
regarding the issues, consequences and caveats of a peculiar feature. We don't
have strict requirements, but the structure should loosely resemble the
following:

1. Problem Frame (what is the context and which issues this enhancement or
feature will address).
2. Requirements (what are the behaviors required for this feature to be
supported?).

You can take a look at drafts in
https://github.com/meliorence/react-native-render-html/tree/master/rfc[the `rfc`
folder] for inspiration.

[NOTE]
We require RFCs to be written in *AsciiDoc*. If you know
markdown, it is very easy to pick and it ends-up much more powerful and
versatile. Their documentation is of excellent quality, as proven by their
https://asciidoctor.org/docs/asciidoc-writers-guide/[writer's guide].

=== Other

For other type of contributions (documentation, enhancements), we don't __a
priori__ require anything particular.