13
\$\begingroup\$

During RPG design, ones RPG goes through many iterations. If one has a PDF, or a print copy of the rules, or a .docx or what-ever, it is important to know what version you are looking at.

Particularly, when it is being done "open-source"/ community driven. With many people making different contributions and maybe branching off with their own variants.

For a long time, my gaming club was playing a version of Adeptus Evangelion called "AdEva, v2.0 Delta edition". It was split off from the original AdEva ruleset before v2.0 was released, and had changes made by a guy who's character name was "Delta". It is darn confusing when trying to ameliorate changes.

Software has this down pat with version control. You can always just check on a branch and trace its linage.

Unfortunately, plaintext & version control is way way too unfriendly for most people making RPGs for fun (trust me I've tried several times). Particularly, when it is a team effort from people with all kinds of experience. I mean my current project is just 2 of us, and already the other persons lack of tech skills knocks out using version control. AdEva was like 15+ contributors, and 2-3 people gating control to the cannon document (IIRC). I guess that gating is what resulted in forking variants.

What method can I use to ensure it is clear which version of a in-dev RPG a particular copy is? If it involves version numbers how should I update them, etc.

Right now, I am calling my current version alpha-X.y, and plan to continue calling it alpha til I start doing open playtests. Then, I'll call it beta-X.y. X will stay at 1 unless I decide to overhaul the system in a big way. I'll increment y whenever I make changes - if I spend a few hours writing one evening I'll increase y at the end of it.

Other options might be to only increase y when I release a PDF, but some of my playtesters have read-access to the live version: I export to a PDF, so they can read on bus, etc. They might export a PDF and it might be different to another copy that another player exports 12 hours later, with the same alpha-X.y tag in the header.

SemVer can't help me, because SemVer never works without an API to break. I am looking for a system more like SemVer, than like git (or Google Docs) though. Not version control, but version naming.

This is a game-design process question. It is not about published RPGs. Published RPGs normally are X edition with the errata.

\$\endgroup\$

closed as unclear what you're asking by Oblivious Sage, Pyrotechnical, T.J.L., ShadowKras, doppelgreener Nov 29 '17 at 12:55

Please clarify your specific problem or add additional details to highlight exactly what you need. As it's currently written, it’s hard to tell exactly what you're asking. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 3
    \$\begingroup\$ I'm voting to close this question as off-topic because it is about document-versioning systems, rather than RPGs. Just because the document-versioning system will be used for RPGs does not make the question about RPGs. \$\endgroup\$ – Oblivious Sage Nov 28 '17 at 14:49
  • 12
    \$\begingroup\$ @ObliviousSage Ultimately, I think this question just squeaks by. There aren’t many enterprises in which English-language text requires careful versioning; you have either source control for programming, or you have more casual/informal versioning for documents (drafts, etc.). I am not sure there is a better place to ask this question—and this question does have an interest here. \$\endgroup\$ – KRyan Nov 28 '17 at 16:20
  • 5
    \$\begingroup\$ I will vote to reopen this as-is once closed; this is a valuable on-topic question in an area of the site I want to see grow. \$\endgroup\$ – Please stop being evil Nov 28 '17 at 20:07
  • 3
    \$\begingroup\$ I think the answer from @Baskakov_Dmitriy clearly shows why this question can be considered on-topic for this site \$\endgroup\$ – Wibbs Nov 28 '17 at 20:21
  • 1
    \$\begingroup\$ Hi Lyndon, I'm putting this on hold temporarily so we can sort something out. There's some lack of clarity around this question that is drawing concern and flags, especially spurred by your most recent edit: the problem you seem to be facing is around version management, but you've revised this question to scope it down to requesting version numbering scheme. These are wholly different concepts (e.g. the software version control you mention may involve no specific version numbering whatsoever) and I'm concerned you're conflating them and expecting that the second will solve the first. \$\endgroup\$ – doppelgreener Nov 29 '17 at 12:58
8
\$\begingroup\$

I think you're expecting a bit more from your version number than it actually delivers.

To start, yes, you can insert a Git commit ID into your file. There are equivalents in other tools, and you can consider things like Office Change Tracking or similar.

That will let users know "my documents is different from his," but that doesn't really solve the problem of "end-users are unsure of which version is the latest, or how to compare two versions." Especially when you're using something non-sequential, like Git hashes.

Step one: Use Releases

Version numbers are different from commit numbers/hashes in that they identify releases. Every so often, you need to identify a point when you've made substantial progress, and publish this in some form (a PDF export is fine), along with a version number.

You might do this every N days (so version alpha 1.2 is published a week after alpha 1.1, which was published a week after alpha 1.0). Or you might do this at arbitrary points as you make progress (alpha 1.2 has an overhauled gathering system from alpha 1.1).

The point here is that releases, once made, are stable and semi-permanent. If someone says they have an issue with alpha 1.2, you have a way of going back and looking at what alpha 1.2 looked like.

Step two: Lock Down the Live Version

Playtesters should be using your numbered releases. This lets you focus your testing, and get reasonable comparisons.

Your "live" copy of the Google document should only be available to your direct contributors/collaborators/acolytes. These users should be "sophisticated" enough to understand that this version of the document is constantly evolving. They generally shouldn't need a version number... If something is unclear, they should know to get the latest version. If they liked something that has gone, they should know that they need to ask for it to be reintroduced.

Integrating Changes From Multiple Contributors

Dealing with multiple authors is a separate issue from version numbers. Many good changes have been proposed... Anything from a shared Google Doc, to Office change tracking, to Source Control software such as Git.

The important parts here are:

  • You all agree on how new versions are released.

  • You all agree on how to resolve conflicts.

  • You have a workflow that works (or can be made to work) for everyone.

There's no magic bullet here that enables everyone to "just do their thing" and have it work out. You ultimately need someone to resolve contradictions.

Forks

The final complication here is forks: someone publishing a new version of your work under their control (and, therefore, their versioning system). I've honestly never been in this situation, but there really isn't much you can do here.

If your process is tightly controlled, you might create more permissive forks (probably what happened to AdEva). If your process is loosely controlled, you can see forks appear from unmanaged contradictions (the extreme case is each contributor's version is their own fork), or you might see a more tightly curated fork emerge.

Either way, forks are the result of transitioning from a single author's control to the community's control. If you're only at alpha right now, you aren't there yet.

\$\endgroup\$
4
\$\begingroup\$

Use Google Docs

I have experience in designing LARP rules using Google Docs, and it was awesome. LARP rules, even though typically shorter than tabletop RPG rules (around hundred pages against like several hundred pages), need to be a lot more precise, because there will be no constant GM presence to judge each of the rules' applications. It makes them also go through a lot of iterations, which can also cause confusion.

I also have a lot of experience of using Google Docs for different purposes, both together with someone and alone, I use it as my main office program, and I don't even have normal offline office programs installed on my PC.

Why should you use Google Docs, or, to be more exact, Google Drive?

  1. Google Drive is essentially very similar to a normal folder on your computer. You can split your rules in parts that are all in one folder, it makes the amount of confusion a lot less. For example, we had combat rules in a separate document from economy rules, so it is easier to understand what is being changed.
  2. It is completely free. You only need to register a GMail account. Unless you need to store particularly large files, free 15 GB that you get should be more than enough. LARP design has very limited budget, as it is done by volunteers, and the budget is formed by players covering the costs of hosting the event, so being free is a big asset. An open-source RPG likely has zero budget.
  3. It requires very little training to use. If you are trained to use some standard office software like Microsoft Office, or Open/Libre Office, you will learn Google Docs in almost zero time. Basically, all you will have to know are sharing settings and version history control, which require extremely little special effort to use. If you are not interested in learning a lot of new complex stuff, Google Docs offers a lot of functionality that is really easy to learn.
  4. It has many types of files supported: not just plain text, but also drawings, Excel-like spreadsheets etc. We used a Google Spreadsheet for budget calculations, a Google Drawing for the game territory marking, Google Forms for accepting players' data, and a spreadsheet to store it. You probably won't need to calculate budget of an "open-source" RPG, but you might use spreadsheets for other important calculations, which you would typically need Excel for.
  5. You can download any file you can view as any of the common formats with ease, such as .odt or .docx, or .pdf. You can also make a separate copy added to your Google Drive.
  6. Google Drive requires totally no special software to download. If you have one of the common browsers, you can use Google Drive. If you have an Android smartphone, you can have fully functional Google Drive too! Also means that system requirements to use Google Drive are very low, and you can use it on any PC, even if you are not allowed to install software on it.
  7. Google Drive allows many people to edit the same file at the same time. They will see which parts are being edited by the others. It can go very smooth if you all have good internet connection, or not so smooth -- in the latter case you will have to refrain from editing the very same lines in the same document, but most systems I know don't allow it at all! And, again, you can do it if your internet is good, especially if you use some kind of voice communication when editing, such as Discord, TeamSpeak, Skype, or simply sitting together during an offline meeting. :)
  8. You don't actually need constant internet connection to edit files in your Google Drive. Almost all of the Google Drive functionality is available offline. I do not have experience with working only offline for large periods of time (more than a couple of hours for shared documents, more than a couple of days for solely-edited ones), but you can, for example, edit a file for a couple of hours when you are in a train, and the changes will be automatically uploaded next time you have internet connection.
  9. You can also have non-Google Docs files in your Google Drive. But Google Docs take zero space in your Drive, while 3d-party files do take space.
  10. It has a built-in autosave feature which happens like every few seconds. You won't lose your work if electricity suddenly turns off, or if your OS crashes.
  11. Neither can you lose your files due to HDD failure. You can actually trust Google at storing your files.
  12. It has perfect sharing and version control settings that I discuss in the next two chapters. :)

How do Google Drive sharing settings work?

The Owner of the document has all the rights for this document, and they can only be revoked by the Owner themself: the Owner will need to transfer the document to another Owner.

The Owner, among other stuff, can do the following things with any Google Doc or Google Drive folder:

  1. Add specific people with specific GMail addresses to the sharing list, assigning specific priveledges to each of them. The Owner can also delete people from the list.
  2. Make a sharable link to the document, assigning a priveledge level for any person that gets the link.

The priveledge levels are, by ascending level, are:

  1. "Can view". Your files are not visible to anyone by default, so your data is private, but you can allow specific people to view it, or share it by the link with unlimited amount of participants. Those who are allowed to view the document will also see the editing process going on if there is any. They will not be allowed to see the version history, share the file with someone else and touch the sharing settings at all. In LARP, we use this settings for the players who are allowed (and required!) to read the rules, but certainly not allowed to change them.
  2. "Can comment". Very useful for your beta-readers. Those with this priveledge are allowed to select a portion of the document and enter their comment for it. It is very useful for discussing specific parts of your text. Comments are only visible to other commenters and those who can actually change the document. Commenters are also allowed to suggest changes: they appear in a specific formatting so it is easy to distinguish a suggestion from a finished text. Suggestions are not visible to "viewers", only to those who can edit the text and comment on it. Even if you are allowed to edit the document yourself, it might be useful to use suggestions and comments mechanic so viewers only see your changes when they are ready, but can still access your document by the same link. We didn't have any people who were only allowed to comment, but those features were commonly used.
  3. "Can edit". Those can do pretty much everything: edit the text directly, change sharing settings, accept and reject suggested edits, delete comments and mark them as resolved, etc. They can see and fully use the edit history. This should be used for your core collaborators' team. But keep in mind, again, that "editors" also have ability to suggest edits, and it is often better to rework a part of text via suggested edit and only "accept" it yourself when the rework is ready to be presented.

Note that the very same priveledge levels exist for both your team with given e-mail addresses (obviously, priveledges of each member are separate) and link sharing. If you don't give your link to a lot of people, you might turn link commenting on, but it will turn to be a mess if lots of people have such a right while you also actively work on the document.

If you are working on something with your one close friend and only with him, you can give him a link with editing priviledges. But if it leaks, anyone who finds it will be able to edit the doc.

To manage sharing settings, right click on the file and press "Share".

Here is the official sharing manual.

How does Google Drive version history work?

There is a very good official manual on version control, but for the sake of completeness I will share the basics here.

To access the version history, click on the button right from the "Help" button. It may read in one of the following ways:

  1. "All changes saved in Drive" -- if it was just edited by you, and the edits are successfully saved
  2. "Last edit was made [time frame of the last edit]" -- if it was edited by you some time ago.
  3. "Last edit was made [time frame of the last edit] by [author of the last edit]" -- if it was edited some time ago, and not by you.

You can edit when offline, and there will be text signaling if the changes are saved offline or something goes wrong, but you cannot access version history offline.

When you click this button, you will see a list of versions (revisions), sorted by time (newest first, oldest last). For each version, you will see time and date, and authors.

If you click on a revision, you will be able to see single edit in the text, including the author of each edit, and will be able to roll back to the said revision.

If you click on the three vertically aligned dots right to each revision's name, you will be able to name a revision, briefly signaling out the edits. A switch in the upper right corner allows you to only look at the named revisions or look at all of them at once.

You can signal named edits in the text, like "Version 3.1a: blahblah changed". The best way to ensure that it is very clear which version are you reading on print is adding page headers: they will be added automatically for every page if you press "Insert", then "Header", and then enter the version name/number.

While working on a document, you can enter the edits as "suggested", and name a revision each time you accept anything, signaling it in the text. It is also good to have a written change log. We didn't need it because we didn't need forking of our rules, but some other russians designing LARP with Google Docs did (for example, the one who has created a very popular model of medicine, perhaps the most popular one in Russia).

Releasing new versions

From my experience, it is a very bad idea to allow access to the live version for anyone who is not supposed to edit it. Once you have made a substantial amount of changes, you might decide that you are ready to make a new alpha release. What should you do then?

  1. Update the changelog, which should likely be in the beginning of your document. When you are reading a slightly different version of something familiar, it is very easy to miss important changes. You can go through all of your edits in the Google Doc since the last release, and just write what has changed since then. It is actually better to write the changelog while working on a new version, but if some of your participants fail to do everything right, you might have to recheck, or even decide to do all the versioning yourself, which is not a bad idea. We didn't have proper changelogs during our development, but we had "resolution" documents, where we have wrote what have we decided to change on each of our meetings.
  2. Update the version number. It should be included somewhere on the title page, so you can see it clearly, but don't forget to also add it on a page header, so if you have a printed version and pages get separated, you are not lost in the chaos. Change the document name aswell, so you will not be lost in them. It is a good idea to base your version name on the date and time of the release and on the fork name, so it could read like that: "Version 30.11.2017 2:22 alpha Main_fork", where "Main_fork" is your fork name. Better invent something more or less original, so it is easy to Ctrl+F for it. Don't use common words as fork names.
  3. Make a copy of your document in your own Drive, and freeze any editing of the released one. Revoke editing rights from anyone who has access to it, so they cannot edit the old version, and don't edit it yourself. Name the old document exactly as its version is named, and publish it in whichever way you use: link sharing, exporting to PDF, etc.
  4. Copy the old version's changelog data at the main changelog at the end of the document, so you have a total list of your changes.

This way, any reader will have a very clear understanding which version are they reading, what changes have been done, and, thanks to the good versioning tools, it will be very easy to mark the changes.

How can you have forking?

As mentioned, Google Docs have a built-in tool to make a copy of any document that you can view, including your own documents. This is done via pressing "File", then "Make a copy". The problem is that the copy is not different in any way from the original file, aside from its name: it will be called "Copy of [previous file name]". It will also not inherit the original file's version history. This means that you will rely on marking the changes manually anyway.

If someone wants to fork your project, you may give the following actions, which you can require in your license:

  1. Make a copy of the document via the "Make a copy" functionality
  2. Name your new fork by substituting the old name with your own one. For example, if the old was called "Main_fork", you can substitute it with "Brave_new_fork" in the page headers, on the title page, and in the document name.
  3. Move the changelog of the fork you copied at the end of the document
  4. Start your new changelog with the line that reads something like "Forked from version X of fork Y, named Z, on day DD.MM.YYYY

How can you get a list of changes from a document?

Let's imagine that someone has forked your RPG, made a list of popular changes, but failed to document them properly. To find them, you will need to make a copy of the version that it is based on, and the forked document itself. You need to select all data on the forked document and copy (Ctrl+A, Ctrl+C), then select all and paste it on the copy of the old version document (Ctrl+A, Ctrl+V). You Then look at the changes done by checking the revision history. You will be able to document all the changes yourself, and, perhaps, incorporate into your main fork.


Overall, Google Docs work perfectly for small projects developed by small teams (below like 10 people), but I can't say anything about something larger. Note that, while I have done it for myself, I have zero experience with forking documents as community effort.

\$\endgroup\$
  • \$\begingroup\$ You should address forking. Google Docs have a 'duplicate'/'Make a copy' option that I use for that, but you still need to do something to track split points. You can use shared folders for that if everybody's got Chrome, otherwise you can have a separate doc for tracking the tree or whatever. Most RPG design I've been in almost never forks (at most forking like twice, I think), but it sounds like the OP is in a situation where that's an actual concern somehow. \$\endgroup\$ – Please stop being evil Nov 28 '17 at 20:13
  • 2
    \$\begingroup\$ +1. Having used google docs for versioning my own homebrewed RPG, I've gotta say it works well. \$\endgroup\$ – GMJoe Nov 28 '17 at 20:25
  • \$\begingroup\$ @thedarkwanderer I have made an extra chapter about forking. But you are basically right. \$\endgroup\$ – Baskakov_Dmitriy Nov 28 '17 at 23:11
3
\$\begingroup\$

If you're expecting "regular" people to be able to understand version control systems, and which version they're looking at, you need to make it as simple as possible.

Use "Who" and "Date" as your version number

The key is, as others have mentioned, that you need to have regular "releases". Don't think of there as being a "live" version at all, there's just regular releases of a version of a document. The version number should be the date (I'd recommend the ISO 8601 YYYY-MM-DD format), as well as who is releasing it (as you're concerned about people maintaining their own branch). If you need to release multiple times in a day, append a revision number or just the time (in your local time zone or UTC) like "White 2017-11-28-1930" (assuming that you want to use "White" as the "who").

The details of how this is maintained, or how one easily finds differences between different releases, depends greatly on any software you're trying to use in order to help maintain it. But if your question is how to "ensure it is clear which version of a in-dev RPG a particular copy is", then it's the only way that makes it clear (1) who made it, and (2) what version it is, and whether it's older or newer than another version.

If you're expecting that one group would be the only team to release versions, then you might not need to be as clear about having the "who" in your release string. But if there might be forks, then it makes it clear which group released it, and then other releasers or you could include other changes as they see fit (subject to the usual copyright/licensing/etc. issues). Finding differences could of course be made easier with a source control repository that everybody uses, but most every word processing program has a "show differences" feature, so if you get digital copies of things it should be possible to figure out what's different between each version, and with a clear designation of "who" and "date" it should be clear to everybody which release of a document is being discussed.

\$\endgroup\$
-3
\$\begingroup\$

In point of fact you can use version control systems (e.g. Git) just fine with any sort of files at all, so your complaint about plaintext is misaimed. You can use Git with PDFs, and unless you're going to get into branching, which I really do hope you wouldn't need to...Wouldn't the version control work fine? You could have x.y.z for (edition) (major) (minor) somewhere in the file, if you really felt like it. Just buy a private repo on GitHub or set up something else with a web interface somewhere.

That said, why are you giving them live access in the first place? Surely you don't want to have them snag a copy while you're midsentence...That would be confusing! Don't do it! To use a programming metaphor, it's like giving people code that doesn't compile!

\$\endgroup\$
  • 6
    \$\begingroup\$ Traditional version control isn't a trivial thing for most people to use. The question pretty clearly states that there are non-coder hobbyists involved who need to be able to contribute without understanding GitHub. \$\endgroup\$ – DuckTapeAl Nov 25 '17 at 11:54
  • 2
    \$\begingroup\$ Are you really saying that GitHub is so arcane that you can't pick up the necessary skills to use one branch - commit, pull, push - in a reasonable amount of time? There are GUI clients for crying out loud! The only thing I can think of that would be a problem is merge conflicts except those don't go away without version control anyway. If you really must, just use a Google Doc, you're not going to get anything better. \$\endgroup\$ – Stackstuck Nov 25 '17 at 12:12
  • 6
    \$\begingroup\$ I'm saying that the OP has "tried several times" to get people to use traditional source control, and it hasn't helped. It's fine to challenge a question's premise, but I don't think you've done it well here. Your answer basically just says to use source control again, but without any information on how to solve the unfriendliness issue that the OP is having. You could improve your answer with specific information about how to make source control friendly for non-tech people. \$\endgroup\$ – DuckTapeAl Nov 25 '17 at 20:23
  • \$\begingroup\$ GitHub and/or any Git GUI. \$\endgroup\$ – Stackstuck Nov 26 '17 at 10:55
  • 5
    \$\begingroup\$ @Stackstuck Revision control is easy to use if you A) know what revision control is, B) know enough jargon to understand the documentation, and C) know how to organise and structure a project in a way that makes it amenable to revision control. None of those things are common knowledge to people who aren't software developers. Yes, it's easy to use revision control once you know how to use it; most things are easy once you've mastered them. Until then, they're arcane - and revision control is no exception. \$\endgroup\$ – GMJoe Nov 26 '17 at 20:02

Not the answer you're looking for? Browse other questions tagged or ask your own question.