Latest revision as of 21:06, 21 September 2021

Page Updated:   2021-09-21

This is about a Roll20 feature exclusive to Pro-subscribers (and often to players in a Game created by a Pro-subscriber). If you'd like to use this feature, consider upgrading your account.

Main Article: Building Character Sheets

Written by Andreas J.

A guide on how to contribute changes to character sheets on Roll20, with an emphasis on updating existing character sheets, and what to take into consideration before submitting changes to them. This is a living document, and might change over time.

It is assumed that the reader already has a basic understanding of how to code the changes they want and knows kinda how to submit their changes to Roll20's GitHub repository.

The author doesn't claim to follow this guide to the letter, but sees this as an guide to do development in a "close-to-ideal" way, taking into account as many major factors as feasible any give time, while not going overboard & letting the guide overshadow or stop someone from contributing.

This guide is subjective, and doesn't necessarily reflect the opinion of the majority of sheet authors, or Roll20, just the main author. I want to highlight that GiGs(a prominent sheet author), disagrees with my emphasis on asking for permission of previous editors of sheets, as it goes against the open nature of collaboration. I have yet to fully absorb his criticism or updated the guide related to this. Andreas J. (talk) 12:07, 1 April 2021 (UTC)

The main take-away should be:

Communication is key. -Someone wise, probably

Main sections of the guide:

• CSE vs. Legacy Sheet - Thoughts on making sheets with CSE, or keeping with the old Sheet Framework
• New Character Sheet - when creating a new sheet
• Existing Sheet - things to consider when updating/contributing to existing sheets
• Programming - General programming & Best Practices

[edit] General

When submitting changes to existing sheets that are available in Roll20's Character Sheet selection, you can't just go gung ho and make any changes you want without taking into consideration the existing users & the sheet's author/maintainer.

This is a rundown of the major sections of this Guide.

• The Checklist will help you avoid common pitfalls and considerably reduce the risk of making changes that will break existing games using it, or get angry messages for making changes that make the sheet worse for some existing users.
• Existing sheet
  • Sheet Authors & Maintainers: pointers on communicating with a sheet's original creator/active maintainers and tips on collaboration.
  • The Sheet users: looks at different types of changes, from the perspective of how existing users of the sheet are impacted. Includes suggestions on how to update sheets in a backwards-compatible way and how to contact/communicate upcoming changes to the users.
• New Character Sheet advice on how, and if, a new sheet should be created, and what to consider when designing it.
• Programming: Best practices on programming in general, code health, Git/GitHub, useful tools and other things that aren't covered by the previous sections.
• Collaboration: tips on how to collaborate and code with others (WIP)

[edit] Checklist

This is a useful checklist to go through for anyone submitting changes to the Roll20 repository, to minimize the risk of something going wrong or forgetting something.

If you can in good conscience check off all boxes in the Primary list, the chance of anything going wrong is exceedingly small. #'s 1 through 7 are the same checks that are shown on GitHub when you submit your PR

Primary Checklist

• 1. □ Have you tested this update in Roll20 using the Sheet Sandbox?
• 2. □ Do you have the approval of this update by the sheet author/active maintainer, or been in contact with the latest contributor?
• 3. □ Have you given a summary of the changes in the PR description?
• 4. □ Have you made sure you're only making changes to a single sheet in ths PR?
• 5. □ If the sheet have a Version function/number, have it been updated?
• 6. □ Is this a bugfix?
• 7. □ If this is a Larger update, have you had others help test the changes?
• 7a. □ If this is a Larger update, have you previously submitted a notification in the sheet, informing users of the upcoming changes?
• 8. □ Does this update change attribute-, button-, or template-names?
  • 8a. □ If attributes are changed, have measures been taken to migrate attributes of existing sheets?
  • 8b. □ If attribute-, button-, or template-names are changed, have you considered how this will break current macros used by existing users?
• 9. □ If something is changed how it works, is this change a proper upgrade of the feature, instead just a unneeded change in how it works that might make things harder/more annoying for existing users?
• 10. □ If you update images, have you changed the reference paths to point to Roll20's master repo(instead of any temporary reference)
• 11. □ If this update removes features, have existing users been given a change to voice their option, or considered to create option to hide this feature instead?

Secondary Checklist

If you want to go the extra mile to ensure your PR is great.

• 1. □ Have you tested the sheet on both Chrome & Firefox?
• 2. □ Have you had someone else test this update?
• 3. □ Have you updated any Readme/Changelog, or relevant documentation?

TODO - GitHub-ready version of checklist that can just be copy-pasted into the PR description.

Roll20's GitHub Checklist

The checklist provided by Roll20 when you create a PR. You check/fill the boxes by either replacing the space between the "[" and "]" with a "x", or after you have submitted the PR, you can just mark them normally, as they behave normal once created.

• 1. □ Does the pull request title have the sheet name(s)? Include each sheet name.
• 2. □ Is this a bug fix?
• 3. □ Does this add functional enhancements (new features or extending existing features) ?
• 4. □ Does this add or change functional aesthetics (such as layout or color scheme) ?
• 5. □ If changing or removing attributes, what steps have you taken, if any, to preserve player data ?
• 6. □ If this is a new sheet, did you follow [Building Character Sheets standards](https://wiki.roll20.net/Building_Character_Sheets#Roll20_Character_Sheets_Repository) ?

[edit] How Roll20 handles Pull Requests

Pull requests are processed weekly and should be submitted no later than 6am PST Mondays, roughly 13:00-14:00 UTC. Earlier submissions are encouraged to allow for peer review from other contributors. On Monday/Tuesday, a Roll20 staff member will give a cursory review the PRs to ensure it meets the standards documented on the Roll20 Wiki. Even if the PRs are merged on Monday, it's not until Tuesday Midday/(US time-zones) that the changes get pushed live, alongside Roll20's own weekly updates. When Roll20's Tuesday/Weekly update are implemented, they will release a "Release Notes"-post in the Announcement Subforum.

Roll20 doesn't usually test code changes submitted by the community, but relies on people having read the Contribution Readme & the Minimum Requirements & Best Practices, answer the Roll20's GitHub Checklist, and submitter having tested the changes themselves. They seem to skim through the code & files to check for any glaring changes, but as there are several hundreds of sheets and some PRs can be massive, it's unrealistic for them to be able to do a full code review, so realistically speaking, your code gets merged without testing.

This means that as long as you don't make any elementary mistakes in your GitHub PR, Roll20 will approve, merge, and push live you changes, even of your update introduces major bugs, or doesn't take into consideration the sheet's author/active maintainer.

On rare occasions Roll20 devs stops and ask if a major update have been coordinated with the sheet's author/active maintainer, or to double-check that the Roll20's GitHub Checklist have been properly considered.

Only on rare occasions does Roll20 reverse bugged sheet updates outside the weekly Tuesday updates, and it's basically unheard of them having merge/push live a hotfix for community sheets, but have on rare occasions done it for Official sheets. If a small-to-moderate bug goes live due to a bad PR, one can expect the issue to be fixed at earliest the following week's Tuesday.^source

[edit] How to make a good Pull Request

1. Follow the instructions in the PR template
2. Only edit one sheet per PR
3. Rather give too many details, than too little. You don't want your update be delayed by a week just because you didn't address the issues brought up in time.
4. If you aren't the sheet's regular maintainer, ping the sheet author/maintainer to inform them/other of the upcoming changes. Read Sheet Authors & Maintainers for details.
5. If any, link any relevant Forum discussion/GitHub Issue.
6. Create readable git commit messages.

[edit] Common Reasons for rejection/delay

Even if the Roll20 devs don't fine-comb each PR, there is a number of common reasons why your update might get help up.

1. There are merge conflicts in the PR. Check either GitHub or the Git guides to resolve this.
2. Your explanation for the changes are insufficient. If you do a large overhaul
3. There are changes to more than one sheet. PRs should only edit one sheet at a time. Check the Git guide for how to submit more than one PR the same week.
4. You are removing/adding unrelated files
5. You are trying to submit a manually translated sheet as a new sheet. See Internationalization & Translations
6. New sheet, for a system that already have multiple sheets. Roll20 prefers the community improves existing sheets rather than adding new ones.
7. New sheet, you've used <table> in the sheet design. Roll20 insists sheets use more modern layout methods. Doesn't apply to existing sheets.
8. New sheet, the game isn't readily available and they request more info. If a source for the game rules(free, or paid) can't be found by using the sheet's name in a web-search, they might ask for references. Roll20 accepts sheets for "homebrew" systems as long as it's "readily available", but might temporally turn down a sheet that haven't yet been published if it doesn't have a publicly available ruleset in some form. For example, if a Kickstarter RPG have only released rules to backers, but the Kickstarter is closed or there is no quickrules set, the game isn't really considered "readily available".

[edit] CSE vs. Legacy Sheet

Main Page: CSE

Since CSE was rolled out, people have had to decide if they want to keep their sheet using the old framework, or adjust sheets to use the stricter html/css rules, to get access to the new features.

There is still some instabilities & rollbacks with CSE, so it might be smart to adapt sheet code to be compatible with both Andreas J. (talk) 12:07, 1 April 2021 (UTC)

Multiple sheet authors have concluded that adding sheet- to all classes mentioned in HTML and keeping the .sheet- prefix in the CSS is a smart choice, as this have been reported to make the sheet compatible with both CSE and Legacy Sheet styles.

The official CSE advice is for us to remove the sheet- parts, but also points out that if the built-in roll20 rows & columns are used, you need to keep sheet- when referenced in the HTML:

Migrating from Legacy to New System:

• Remove any hard-coded references to the following from your CSS and HTML and fix whatever issues it has caused.
  • “Sheet-” class
• If you’re using our provided Roll20 grid, add “sheet-” to your HTML class attributes where those classes are being used.

This, along with the observation that CSS for roll templates still require the .sheet- part, it seems all around more resilient for the code to add sheet- to all CSS & HTML sections, rather than needing to have two versions of the code.

[edit] New Character Sheet

What to consider when creating a new sheet.

[edit] When to update old, or create new?

If a game is popular, and there isn't really anything wrong with the existing sheet, but you want to rewrite it from scratch to be more powerful, it can very well have a merit to create an "Advanced" sheet for the same system.

[edit] Where to start

If there exists Roll20 sheets for closely related systems, it might be a good idea to start from that sheet, rather than starting from zero.

Maybe there are several sheet that have designs that is worth taking inspiration from?

The Sheet Request have a good checklist that to go through when you want to start, and answering those questions yourself will likely make things more clear.

[edit] A specific Game Edition, or be more flexible?

Example: Are you going to create a sheet that would both work for playing 3rd Edition & 3.5 E with options to change settings, or are you focusing to create a sheet tailored for 3.5 E?

Are you considering leaving space for implementing optional or homebrew rules for the sheet/system?

[edit] Design

[edit] Layout - Paper or something else?

Is it a good idea to keep as close as possible to the layout of the paper version of the sheet, or does Roll20 and the digital environment offer features that outweighs familiarity?

Should you have one larger page with everything, split things up on separate pages(like with paper), or go for a more modular design like done in computer games where you can hide/toggle various sections at will?

Should you design the sheet with fixed dimension, or make it flexible with how wide/tall you keep the sheet open?

[edit] Roll Buttons

• Should they look like buttons, or blend in on the layout?
• Do you need/want tons of buttons placed in every relevant place, or only use fewer buttons that constructs the macro based on some menu? A mix?

• Complete Guide to Macros & Rolls For details on creating Roll macros
• roll buttons for creating roll buttons on sheets specifically.

[edit] Roll Template

Are you creating a custom Roll Template to fit the sheet?

How much info do you want to display on the roll, and how much options/settings do you want to include?

[edit] Player/NPC sheets/pages

It can be a good idea if Player & NPC sheets share as many attribute names as possible, making it easier to switch/converting between both templates for a character.

This could also result in most macros and buttons working for both Player's and NPCs.

[edit] Code

[edit] Readable code

Structuring code to be readable by other is a good idea, making it easier to contribute. It will also make it easier for you to understand things when you've forgotten things.

Using understandable, full-length variable names instead of cryptic shorthand in your code makes it more understandable.

Placing Roll Templates and Sheetworkers at the bottom of the sheet, and having any hidden inputs just above them is a common practice.

[edit] Autocalc vs Sheetworkers

Sheetworkers are more powerful & flexible to create, and should be favored when creating ways that stats & attribute changes or are calculated based on others.

Autocalc are more simple to write, but doesn't play well when mixed with Sheetworkers, Token Bars, or API.

[edit] Attribute & Roll Button Names

How you name your attributes and roll buttons will impact how easy they are to be used in macros, or recalled in general.

Is roll_init or roll_initiative better?

More frequently used attributes would make more use of short names, while less used ones wouldn't really suffer if you give it a name that's obvious.

Same goes for Roll Templates.

[edit] Existing Sheet

Suggestion on how to approach contributing to existing character sheets in the Roll20 GitHub repository.

[edit] Sheet Authors & Maintainers

If you want to contribute to a sheet you haven't created yourself, you should be in contact with the sheet's author or active maintainer, as depending on the extent of your update, it might throw a wrench in their plans. If they are working on an update to the sheet themselves, and you have merged your changes, it is likely to complicate/undo much of what they have been working on, or considerably conflict with what you have implemented.

More than once have original sheet author, even active ones, given up on sheets due to massive changes submitted by others reworking their sheet without them being contacted.

[edit] What is the Sheet's History?

1. Does the sheet have instructions or a Readme/Changelog, mentioning who/how to contact someone related to the sheet, or a desired approach to contributions?

2. When was the last major update done, and by whom? Open the sheet's folder on GitHub and then open the History/commits section, and scroll through the latest couple of commits/PRs. Check if the original sheet author or someone else have made large commits (that isn't just changes to the translation files) in the last year or two.

3. Who are credited as sheet authors in the sheet.json file? You can contact the authors by copying the numbers in the "Roll20 ID", and adding it to the end of https://app.roll20.net/users/, and going to that page. It will bring up that users roll20 page, and you can then send them a private message through Roll20. (e.g. if one of teh numbers is 123456, then go to https://app.roll20.net/users/123456).

[edit] Suggestion on sheet approach

[edit] You are the Author/Maintainer

You can skip this section and jump directly to Sheet users.

[edit] Actively Updated Sheet(by Author/Maintainer)

100% contact whoever is actively updating the sheet, even before you start working on your intended changes, tell them what you intended to do, and asking if they are currently working on an update.

Coordinate with them on how your potential changes could be incorporated into their WIP, or if it's even needed.

If you don't get an answer in some time, make a post on the Character Sheets & Compendium and ask about the situation with the sheet. The community is active, and it's likely someone else have some idea if the sheet is actively updated.

[edit] Sporadically Updated(by multiple users)

Look at the commit history and contact the last user who made anything more than a minor bug fix, and as their opinion what you are considering updating.

[edit] Seemingly abandoned sheet

If there are several years since the sheet was edited, Look at the commit history and contact the last user who made anything more than a minor bug fix if it seems they still are active with updating other sheet. This can be checked by looking at closed PRs searching for the github-name of the submitter.

You're likely fine to submit changes, but could be a good idea to still consider the points mentioned in Sheet users.

For example, if the author was GitHub user Anduh, this reveals all their latest merged updates:

[edit] Add someones else's sheet to the Repo

If you found someone else's code for a Roll20 sheet that isn't already available in Roll20, contact the person out of courtesy and tell them you want to submit the sheet.

There might be a good reason why they haven't done it yet. Besides, if you submit the code and makes changes to it, it will make it impractical or near impossible for them to later submit their code if they continue developing it, as it would now be a duplicate of an existing sheet and be turned down, forcing them to either try to rework everything to fit as changes to the submitted sheet or just give up.

[edit] Sheet users

It's good to think about existing users of the sheet when making an update, as you & your group aren't the only one who are affected by the update, and changes to features you might not use as much might cause significant annoyance/complications for others.

[edit] New Feature

Creating a new feature/section is often better than changing how an existing things works, as any change you subjectively might think as a straight upgrade without any negative impact, it's not an objective truth.

In some cases a long-standing, but less complex feature is better kept, than to replace it with something that have more features/is cooler more frequently. Creating a new feature as an alternative to the existing thing might in many case a good idea.

[edit] Notifying of Upcoming Changes

If you're planning on making an update that makes lot of changes, or could result in reasonable objections by some, it would be a good idea to create a "notification" update on the sheet informing of the possible future update, and your contact info.

See Sheet_Author_Tips#Sheet_Changelog_and_notification for more details

[edit] Creating Options

If you update a sheet to contain new options on some way, it's good to consider if these new options should be remain unselected by default, and up to the users to start using the feature or not.

Creating new features to the sheet that remains optional is a good way to keep the sheet working as it have in the past, while still making new things available.

Example 1: If a simple sheet has roll buttons that straight away rolls the dice after being pressed, and you introduce an option to apply modifiers to the roll before the roll is executed, consider implementing the feature in a way that doesn't force the feature on old users. If you enable this modifier-popup by default, without an option to turn it off, you have then forced everyone to spend extra time to dismiss the popup when they roll, slowing down their game whether they want it or not.

Example 2: Revamping a sheet to have more appealing graphics/layout can be nice, but could result in something that's less readable and harder to navigate than the old version, and some users would prefer to keep the old version. In this case, it could be a great idea to implement the new layout as an optional feature users can use to toggle between the simple(old) layout and the graphical layout.

[edit] Changing/Migrating stats

If you change attribute-, button-, or template-names, consider that this might break user-made macros, API & make any documentation/guide outdated. So if possible, don't change names if it isn't needed.

Changing a section from being a static section into a repeating section should either get a version-based stat migrating sheetworker, or leave the old section easily accessible in a separate tab or something so that users can migrate them manually. Still, if someone have made massive games with the old stat-blocks, it would result in needing to migrate 10s or 100s of characters stats form the old to the new ones, so creating a sheetworker to automate the change would be ideal.

Example. In 2020, Roll20 changed the attribute-name of D&D 5E NPC's trait description desc, into description, which resulted in macros that had been used for years without problem with the sheet to start malfunction when used with any NPC's created after the update was made, while still working with the old NPC's as they still had the desc-attribute.

[edit] Changing Features

If you intend to change how a feature works, you should consider if the change is an upgrade across the board, or if it is more of a subjective change on how you feel it should work, while it might negatively impact the common users experience without and actual benefit.

[edit] Removing Features

Rarely is it warranted to remove an existing feature from a sheet, and it's always better to make it optional by creating a toggle/setting to hide the feature. If removed, it can permanently wreck the games where the feature is used.

Just because you think the feature is redundant or unneeded, doesn't mean all the sheet users thinks that way. That is even true for homebrew features that isn't part of some official version of the game, and could be labeled as "homebrew/unofficial" to underscore it's not a default feature, but rather something more subjective.

Example:

Someone removed a number of extra health boxes from a World of Darkness sheet that wasn't part of the "normal" player character sheet, but the changes what later reverted when several users of the sheet complained that removing them would downgrade the sheet for those who used it for High-Level NPCs or for homebrew games where players could have stats beyond the normal limit.

[edit] Programming

Thoughts, best practice, code health, Git/GitHub, useful tools and other things that is good to consider when creating or updating sheet, which isn't already covered in the previous sections.

[edit] Tools

Programming using an IDE or a text editor made for programming such as Sublime Text or Visual Studio Code is a good idea.

Sheet Author Tips have a number of suggestions for this.

[edit] Names/Style

Follow the same naming style/convention for attributes, CSS classes, functions etc. so the sheet stays predictable/consistent. This will keep the sheet easier to maintain in general, and more predictable for users and code contributors. (e.g. CamelCase, similar use of underscores etc)

Recommendation for character attributes names is to use snakecase. This will help avoid problems related to sheetworkers & calling/updating attributes, as there are some places where they need to be all lowercase, and other places things might be case-sensitive.

Follow similar code indention style (e.g. space vs tabs).

[edit] Versioning

Using and tracking a version number for the sheet visibly will make it easier for people to know when sheet have been updated if the number increases.

Creating a function for updating stats/attributes, or to notify users of new/upcoming changes to a more complicated sheet is also a good idea.

See Sheet_Author_Tips#Sheet_Versioning for more details.

[edit] Git/GitHub

1. Write commit messages that describes your update, and possibly start with the name of the sheet and version of the update. It will make it easier to go through the sheet history and see at a glance what each commit does
2. If you make a massive sheet update, it's a good idea to periodically create a new commit as you work, rather than save all up into one single, massive commit. This will make it easier for you & others to find when/where a bug is made when looking at changes between commits.

[edit] Documentation

If the Sheet has lots of features, or have existing Documentation/Readme/Changelog, update it with some info on your changes, following the same version naming convention, if it have one.

This will make it easier to follow when updates are made if there is a precedence on how it's done in the past.

[edit] Collaboration

Learning how version control works, and how to use Git properly will make it easier to collaborate with others on sheet updates, without having to run everything through Roll20's repo.

The Short Git Guide has a section on collaboration that can be useful.

Also check Sheet_Author_Tips#Sharing_code.2Fcollaboration.

[edit] Related Pages

• Building Character Sheets - The core article on Creating/Editing Character Sheets
  • CSS Wizardry - Common tips & tricks to implement features within Roll20's constraints
• Complete Guide to Macros & Rolls Main Article collecting all info on macros & dice rolling on one page
• Sheet Author Tips More advanced tips for creating/maintaining sheets, workflow, & useful tools
  • Sheet Sandbox – the better editor to use when you code your character sheets
• Beginner's Guide to GitHub how to use GitHub to submit sheet changes or new sheets to Roll20
• Git Guide how to use the Git CLI(Instead of GitHub Desktop) when working with Roll20 sheets & submitting changes to Roll20