|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Homebrew |
| 4 | + |
| 5 | +Homebrew contributions (conversions, original content) should be made against the [homebrew repository](https://github.com/TheGiddyLimit/homebrew/). See the guidance there for more information. |
| 6 | + |
| 7 | +## Typo Fixes/Etc. |
| 8 | + |
| 9 | +Small fixes and tweaks, especially typos, should be reported via the "typos etc." channel in our [Discord](https://discord.gg/5etools). If you do not use Discord, opening an issue on GitHub is acceptable. |
| 10 | + |
| 11 | +## Feature Requests and New Features |
| 12 | + |
| 13 | +All feature requests should be done via the `/featurerequest` bot command in our [Discord](https://discord.gg/5etools). |
| 14 | + |
| 15 | +Should you wish to directly contribute code towards a new feature, preferably get in touch via [Discord](https://discord.gg/5etools) first. If the feature is deemed acceptable, and significant/distinct enough that it makes sense for a third party to undertake the work, then a pull request can be opened on GitHub. |
| 16 | + |
| 17 | +In general, the following should be noted: |
| 18 | + |
| 19 | +- Features which place an additional long-term maintenance burden on the project will not be accepted. |
| 20 | +- Features which significantly deviate from the D&D 5e canon (for example, complex custom random generators; support for system forks or significant homebrew) will not be accepted. |
| 21 | + |
| 22 | +## Bug Reports |
| 23 | + |
| 24 | +Bugs should be reported via the `/bugreport` bot command in our [Discord](https://discord.gg/5etools). |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## Developer Notes |
| 29 | + |
| 30 | +### Data Sources and Versioning |
| 31 | + |
| 32 | +Only "official" (that is, published by WotC) data is to be included in the site. Anything else should be added to the homebrew repository. Some exceptions to this rule are: |
| 33 | +- All Adventurers League (AL) -specific content is to be kept in the homebrew repository. While much of this content broadly falls under the "published by WotC" umbrella, a good deal of it doesn't. For the sake of consistency/cleanliness, all AL content is to be considered homebrew. |
| 34 | +- Anything published in the Dragon+ magazine. |
| 35 | +- Anything veto'd by the maintainers of this repository. |
| 36 | + |
| 37 | +Prioritise RAW above all else. Aim to provide a 1:1 copy of the original data. Obvious typos (for instance, mathematical errors in creature stat blocks) may be corrected at the discretion of the maintainer(s). |
| 38 | + |
| 39 | +Aim to use the latest version of any published material. Older versions which are sufficiently different (and relevant to community interests) can be moved to the homebrew repository. |
| 40 | + |
| 41 | +The primary source for an entity should be that under which it was first released. Exceptions to this rule include: |
| 42 | +- The entity was originally released in a "partial" or "pre-release" form. For example, races from WGE were later re-released in ERLW. |
| 43 | +- The entity was originally released in a published adventure, but was later re-printed in a generic supplement. For example, the demon lords in OotA were re-printed in MTF, or the Haunted One background in CoS was re-printed in VRGR. |
| 44 | + |
| 45 | +#### Page-Specific Notes |
| 46 | + |
| 47 | +*Languages page.* As there is no well-defined RAW format for language data, the languages page collects together information from several disjoint places. A priority list of sources to be considered is: |
| 48 | +- The "Languages" section on PHB p123 |
| 49 | +- official sources, in order of: |
| 50 | + - PHB > (DMG) > MM |
| 51 | + - Other "official" (i.e. published) products in release-date order |
| 52 | + - "Unofficial" products (i.e. Unearthed Arcana; Plane Shift) in release-date order |
| 53 | + |
| 54 | +Within this ordering, the following prioritisation should be made: |
| 55 | +- text that directly refers to or describes a language, in order of first appearance in the product (i.e. if a language is mentioned on page 2 and 10 of a book, the entry on page 2 should be taken as the primary source) |
| 56 | +- text that is given for player use (e.g. the "Druidic" feature of the Druid class) (the text of which may have to be adapted to fit a reference format; i.e. changing "You can understand..." to "A speaker or X language can understand...). |
| 57 | + |
| 58 | + |
| 59 | +### Target JavaScript Version |
| 60 | + |
| 61 | +Any language feature which is available in both main-line Chrome and main-line Firefox, and has been available for at least six months, may be used. |
| 62 | + |
| 63 | +### Style Guidelines |
| 64 | + |
| 65 | +#### Code |
| 66 | + |
| 67 | +- Use tabs over spaces. |
| 68 | + |
| 69 | +#### CSS |
| 70 | + |
| 71 | +- The [BEM](http://getbem.com/) ("Block Element Modifier") naming strategy should be used where possible. |
| 72 | + |
| 73 | +#### Data/Text |
| 74 | + |
| 75 | +- Format JSON to match the default output of JavaScript's `JSON.stringify` (using tabs for indentation), i.e. one line per bracket and one line per value. JSON files programmatically generated from other JSON files (i.e. those stored in `data/generated`) should be minified, however. |
| 76 | + |
| 77 | +- When "tagging" references in data (e.g. `{@creature goblin}`), the following rules apply: |
| 78 | + - Only tag references which are _intended as references_. For example, the Wizard class in `You gain one cantrip of your choice from the wizard spell list` should be tagged, whereas the Wizard class in `Together, a group of seven powerful wizards sought to contain the demon` should not be tagged. One is a reference to the mechanical class, one is merely the casual usage of the word "wizard." |
| 79 | + - In a similar vein, never tag anything within a `quote`-type block. Even if the quote directly refers to a specific creature, we can assume the quote is from a universe/perspective in which (for example) stat blocks don't exist, and therefore the tag should be omitted to maintain the flavor of the quote. |
| 80 | + - Within data from a source, avoid referencing content from a source printed after the publication of that source. For example, MTF content might reference SCAG deities, but SCAG deities should refrain from referencing MTF content. |
| 81 | + |
| 82 | +### JSON Cleaning |
| 83 | + |
| 84 | +#### Trailing commas |
| 85 | + |
| 86 | +To remove trailing commas in JSON: |
| 87 | + |
| 88 | +Find: `(.*?)(,)(:?\s*]|\s*})` |
| 89 | + |
| 90 | +Replace: `$1$3` |
| 91 | + |
| 92 | +#### Character replacement |
| 93 | + |
| 94 | +- `’` should be replaced with `'` |
| 95 | +- `“` and `”` should be replaced with `"` |
| 96 | +- `—` (em dash) should be replaced with `\u2014` (Unicode for em dash) |
| 97 | +- `–` should be replaced with `\u2013` (Unicode for en dash) |
| 98 | +- `−` should be replaced with `\u2212` (Unicode for minus sign) |
| 99 | +- `•` should be not be used unless the JSON in question is not yet covered by the entryRenderer, i.e. should be encoded as a list |
| 100 | +- the only Unicode escape sequences allowed are `\u2014`, `\u2013`, and `\u2212`; all other characters (unless noted above) should be stored as-is |
| 101 | + |
| 102 | +#### Convention for dashes |
| 103 | + |
| 104 | +- `-` (hyphen) should **only** be used to hyphenate words, e.g. `60-foot` and `18th-level` |
| 105 | +- `\u2014` should be used for parenthetical dash pairs, or for marking empty table rows. |
| 106 | +- `\u2013` should be used for joining numerical ranges, e.g. `1-5` should become `1\u20135`. |
| 107 | +- `\u2212` should be used for unary minus signs, in the case of penalties. For example, `"You have a -5 penalty to..."` should become `"You have a \u22125 penalty to..."`. |
| 108 | +- any whitespace on any side of a `\u2014` should be removed |
| 109 | + |
| 110 | +#### Convention for measurement |
| 111 | + |
| 112 | +- Adjectives: a hyphen and the full name of the unit of measure should be used, e.g. dragon exhales acid in a `60-foot line` |
| 113 | +- Nouns: a space and the short name of the unit of measure (including the trailing period) should be used, e.g. `blindsight 60 ft.`, `darkvision 120 ft.` |
| 114 | +- Time: a slash, `/`, with no spaces on either side followed by the capitalised unit of time, e.g. `2/Turn`, `3/Day` |
| 115 | + |
| 116 | +#### Convention for Dice |
| 117 | + |
| 118 | +Dice should be written as `[X]dY[ <+|-|×> Z]`, i.e. with a space between dice and operator, and a space between operator and modifier. Some examples of acceptable formatting are: `d6`, `2d6`, or `2d6 + 1`. |
| 119 | + |
| 120 | +#### Convention for Item Names |
| 121 | + |
| 122 | +Item names should be title-case, with the exception of units in parentheses, which should be sentence-case. Items who's volume or amount is specified by container (e.g. `(vial)`) treat the container as a unit. |
| 123 | + |
| 124 | +### Mouse/Keyboard Events |
| 125 | + |
| 126 | +Avoid binding ALT-modified events, as these are not available under MacOS or various Linux flavors. Binding SHIFT-/CTRL-modified events is preferred. |
| 127 | + |
| 128 | +### Dev Server |
| 129 | + |
| 130 | +Do `npm run serve:dev` to launch a local dev server that serves the project files on [`http://localhost:5000/index.html`](http://localhost:8080/index.html). |
| 131 | + |
| 132 | +### Version bump |
| 133 | + |
| 134 | +Do `npm run version-bump -- [OPTION]`, where `[OPTION]` is one of the following: |
| 135 | + |
| 136 | +- `major` to increment the major version (`1.2.3` will become `2.0.0`) |
| 137 | +- `minor` to increment the minor version (`1.2.3` will become `1.3.0`) |
| 138 | +- `patch` to increment the patch version (`1.2.3` will become `1.2.4`) |
| 139 | +- a version number (like `1.2.3`) |
| 140 | + |
| 141 | +It will first run the tests and fail to increase the version if the tests fail. |
| 142 | +It will then automatically replace the version in the files where it needs to be replaced, create a commit with the message `chore(version): bump` and create a tag (in the form `v1.2.3`) at the commit. |
| 143 | +This feature can be easily disabled by doing `npm config set git-tag-version false`. |
| 144 | + |
| 145 | +### Service Worker |
| 146 | + |
| 147 | +The service worker--which adds a client-side network caching layer, improving performance and allowing offline use--is not committed to the repository, and so must (optionally) be built locally. This can be done using either: |
| 148 | + |
| 149 | +- `npm run build:sw`, to build a development version which outputs useful log messages |
| 150 | +- `npm run build:sw:prod`, to build a production version |
| 151 | + |
| 152 | +Both versions handle caching for the same files, which is an index of your local files on disk. |
| 153 | + |
| 154 | +Note that building the service worker is optional. |
| 155 | + |
| 156 | +Note that while using the service worker, some files are served cache-first (see the comments in the service worker files for more information). Care should be taken to either disable or work around the service worker when developing locally, as local changes may not otherwise be visible when refreshing a page. |
0 commit comments