|
| 1 | +:hide-uri-scheme: |
| 2 | +ifdef::env-github[] |
| 3 | +:tip-caption: :bulb: |
| 4 | +:note-caption: :information_source: |
| 5 | +:important-caption: :heavy_exclamation_mark: |
| 6 | +:caution-caption: :fire: |
| 7 | +:warning-caption: :warning: |
| 8 | +endif::[] |
| 9 | +:toc: |
| 10 | + |
| 11 | +:rnrh-test-folder: https://github.com/native-html/core/tree/master/packages/render-html/src/__tests__ |
| 12 | + |
| 13 | += A Contributors' Guide |
| 14 | + |
| 15 | +[NOTE] |
| 16 | +If you're starting to read this guide, well thanks for willing to contribute to |
| 17 | +this project! Your effort will be very much appreciated. |
| 18 | +*If you need help*, take a look at <<HELP.adoc#,our dedicated document>>. |
| 19 | + |
| 20 | +[[tickets]] |
| 21 | +== Opening Tickets |
| 22 | + |
| 23 | +After you've read the relevant sections of this document, you can open a ticket |
| 24 | +through GitHub here: |
| 25 | +https://github.com/native-html/core/issues/new/choose. Make |
| 26 | +sure you follow the appropriate template. |
| 27 | + |
| 28 | +[NOTE] |
| 29 | +The art of filling good reports is as important and valued as the art of |
| 30 | +producing readable, maintainable code. Developers tend to rush when filling |
| 31 | +reports because their initiative stems from a place of frustration. This is |
| 32 | +very well understandable, but ineffective regarding the goal of solving one's |
| 33 | +problem. Consider the __time investment / benefits__ ratio: by filling a detailed |
| 34 | +bug report, you might have committed a chunk of your |
| 35 | +valuable time. But **your chances of having a fix merged rapidly have considerably |
| 36 | +increased**. |
| 37 | + |
| 38 | +[WARNING] |
| 39 | +By not following our guidelines and templates, you risk having your ticket |
| 40 | +closed without notice. Sorry about that... our time is also valuable, and we |
| 41 | +cannot help you if you don't help us in the process! |
| 42 | + |
| 43 | +=== Submitting a Bug |
| 44 | + |
| 45 | +[CAUTION] |
| 46 | +If you would like to report a problem, take a look around and see if someone |
| 47 | +already opened an issue about it (see <<HELP.adoc#,HELP>> document). If you a |
| 48 | +are certain this is a new, unreported bug, you can submit a bug report |
| 49 | +https://github.com/native-html/core/issues/new/choose[by |
| 50 | +opening a new issue]. |
| 51 | + |
| 52 | +The most important quality of your bug report is *reproducibility*. It means we |
| 53 | +can easily reproduce and investigate the bug to fix it as quickly as possible. |
| 54 | +If you've never heard of a “minimal reproducible example”, take a look at this |
| 55 | +guide: https://stackoverflow.com/help/mcve. Bellow is a table of different |
| 56 | +types of reproductions: |
| 57 | + |
| 58 | +[TIP] |
| 59 | +If you add screencasts, screenshots, debugging information, or any insights |
| 60 | +that can help us identify the failure as quickly as possible, you can consider |
| 61 | +each a bonus :zap:. |
| 62 | + |
| 63 | +[cols=3*,options=header,frame=topbot] |
| 64 | +|=== |
| 65 | +|Reproduction |
| 66 | +|Efficiency |
| 67 | +|Information |
| 68 | + |
| 69 | +|Regression Test |
| 70 | +|:zap::zap::zap::zap: |
| 71 | +|Offering a PR with a Test which reproduces the issue is the most efficient way |
| 72 | +to have your bug fixed rapidly. More details on the *<<bug-repro,dedicated |
| 73 | +section>>*. You are still required to open a bug report ticket, but you will be able |
| 74 | +to skip many steps. |
| 75 | + |
| 76 | +|Snack |
| 77 | +|:zap::zap::zap: |
| 78 | +|A *Snack* is very convenient for you and for us. You can |
| 79 | +https://snack.expo.io/@jsamr/rnrhtml-template[*start from |
| 80 | +our template*]. *Make sure you set the appropriate version of this library.* |
| 81 | + |
| 82 | +|Git |
| 83 | +|:zap::zap::zap: |
| 84 | +|A Git reproduction is as efficient as a Snack, albeit it might be a little |
| 85 | +extra work for you. |
| 86 | + |
| 87 | +|Code Snippet |
| 88 | +|:zap: |
| 89 | +|A snippet is better than nothing, but we don't consider it __high quality__ |
| 90 | +and might take more time to investigate. Please consider put your snippet into |
| 91 | +a *Snack*. I will take you 2 minutes to configure. |
| 92 | +|=== |
| 93 | + |
| 94 | +Second important thing: try-out the latest version, including pre-releases! For |
| 95 | +more information on this topic, read the |
| 96 | +https://github.com/native-html/core#versions[Versions section |
| 97 | +of the README]. If you can try `master` branch, that would be even better, but |
| 98 | +we don't require it because it could contain breaking changes. To do |
| 99 | +so, simply run the following command: |
| 100 | + |
| 101 | +```bash |
| 102 | +npm install "github:native-html/core#master" |
| 103 | +``` |
| 104 | + |
| 105 | +[[features]] |
| 106 | +=== Proposing a Feature or Enhancement |
| 107 | + |
| 108 | +* Feature requests and enhancements **must** be submitted https://native-html.canny.io/features[in our Canny feature tracker]. |
| 109 | +* You can, *in addition*, consider <<rfc,writing an RFC>> and offering it as a PR. |
| 110 | + |
| 111 | +[TIP] |
| 112 | +You or your company need a feature? Consider https://github.com/sponsors/jsamr[sponsorship or consultancy] and it will be delivered ASAP. |
| 113 | + |
| 114 | +== Pull Requests |
| 115 | + |
| 116 | +[NOTE] |
| 117 | +We require some criterion to accept a pull request. But don't worry, we're also |
| 118 | +willing to help. You're encouraged to start a |
| 119 | +https://github.blog/2019-02-14-introducing-draft-pull-requests/[Github draft] |
| 120 | +and we will be glad to help you build it and make it comply with our |
| 121 | +requirements. If you have any question or need advise regarding your |
| 122 | +contribution, you can also ping us in our https://discord.gg/MwrZmBb[Discord |
| 123 | +#contributing channel]. |
| 124 | + |
| 125 | +=== Bug Fixes |
| 126 | + |
| 127 | +If your PR fixes a bug, you are required to implement a regression test to |
| 128 | +prove your fix is effective, but *don't worry, we will help you*. The simplest |
| 129 | +way is to look at {rnrh-test-folder}[our test folder] and copy/paste an existing __regression |
| 130 | +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 |
| 131 | +know how to implement the test, you can add a "Testing Plan" section in the |
| 132 | +body of your PR. |
| 133 | + |
| 134 | + |
| 135 | +[[bug-repro]] |
| 136 | +=== Bug Reproduction |
| 137 | + |
| 138 | +When you submit a bug ticket, the fastest path for us to resolve the issue is |
| 139 | +by providing a bug reproduction. Take a glance at {rnrh-test-folder}[our test folder] and get |
| 140 | +inspiration by looking at __regression tests__. You are also advised to read our <<DEVELOPING.adoc#, developing guide>>. The PR is ready __when the |
| 141 | +test fails__. |
| 142 | + |
| 143 | +=== Features |
| 144 | + |
| 145 | +[NOTE] |
| 146 | +We recommend you use the |
| 147 | +https://github.blog/2019-02-14-introducing-draft-pull-requests/[draft Github option] |
| 148 | +when you start a Feature PR! |
| 149 | + |
| 150 | +If your PR provides new features, it means that the API of this library will |
| 151 | +likely change. You will be required to test the new |
| 152 | +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 |
| 153 | +discord or within the PR on GitHub. |
| 154 | + |
| 155 | + |
| 156 | +[[rfc]] |
| 157 | +=== Request For Comments |
| 158 | + |
| 159 | +[NOTE] |
| 160 | +RFC are propositions for new methods, behaviors and other API capabilities, or |
| 161 | +the exploration of an algorithmic challenge that is specific to this library. |
| 162 | +These are not Internet Society's RFCs! We don't have a rich multi-stage process. An |
| 163 | +RFC is either a draft, in discussion, or adopted (merged). We thereafter use |
| 164 | +versioning to polish and enhance those specifications. |
| 165 | + |
| 166 | +RFC purpose is to offer drafts for new ideas which goes relatively in depth |
| 167 | +regarding the issues, consequences and caveats of a peculiar feature. We don't |
| 168 | +have strict requirements, but the structure should loosely resemble the |
| 169 | +following: |
| 170 | + |
| 171 | +1. Problem Frame (what is the context and which issues this enhancement or |
| 172 | +feature will address). |
| 173 | +2. Requirements (what are the behaviors required for this feature to be |
| 174 | +supported?). |
| 175 | + |
| 176 | +You can take a look at drafts in |
| 177 | +https://github.com/native-html/core/tree/master/rfc[the `rfc` |
| 178 | +folder] for inspiration. |
| 179 | + |
| 180 | +[NOTE] |
| 181 | +We require RFCs to be written in *AsciiDoc*. If you know |
| 182 | +markdown, it is very easy to pick and it ends-up much more powerful and |
| 183 | +versatile. Their documentation is of excellent quality, as proven by their |
| 184 | +https://asciidoctor.org/docs/asciidoc-writers-guide/[writer's guide]. |
| 185 | + |
| 186 | +=== Other |
| 187 | + |
| 188 | +For other type of contributions (documentation, enhancements), we don't __a |
| 189 | +priori__ require anything particular. |
0 commit comments