docs: rewrite and add a lot of sections based on additional Discord content
This commit is contained in:
Lukas Obermann
+42
-85
@@ -1,104 +1,53 @@
|
||||
# Git Workflow
|
||||
|
||||
Welcome to the introduction on how to contribute to Optolith static data using Git!
|
||||
Before following this guide, make sure you meet all the [prerequisites](./Prerequisites.md)
|
||||
|
||||
You'll need a [GitHub account](https://github.com) (which you probably have if you see this), [Git](https://git-scm.com/downloads) locally installed and a code editor. I'll explain the steps you need to take using [Visual Studio Code](https://code.visualstudio.com) (VSCode), because it's a very easy-to-use and lightweight editor. I will try to avoid the command line in this tutorial, although it is necessary for some steps.
|
||||
|
||||
This tutorial is intended for helpers who have not yet learned about Git and programming. If you are already familiar with both, just jump to the end of the tutorial for a summary list of some rules!
|
||||
This tutorial is intended for helpers who have not yet learned about Git and only covers Mac and Windows specifics. If you are already familiar with Git, just jump to the end of the tutorial for a TL;DR! Also note that there are usually multiple ways to achieve the same thing. This guide will just describe a single way to keep it simple.
|
||||
|
||||
## Getting started
|
||||
|
||||
Create a new GitHub account, if you don't own one already.
|
||||
First, you need to **clone** the **repository** onto your computer.
|
||||
|
||||
Install *Git*. You don't need to change any installation options, just click *Next*—you can change the editor to Visual Studio Code, if you want, though.
|
||||
A **repository** – or simply **repo** – is kind of a special folder with explicit version control. The source repository resides online on GitHub.com – which is where you are probably reading this tutorial right now – but you can create copies of it on other computers so that you can work on them like in normal folders and files.
|
||||
|
||||
Let's *clone* the *repository* onto your computer.
|
||||
To clone a repository, open a terminal in the folder where you want the cloned repository to be in.
|
||||
|
||||
A *repository* – or simply *repo* – is kind of a special folder with explicit version control. The source repo is online on GitHub.com – which is where you are probably reading this tutorial right now – but you can create copies of it on other computers so that you can work on them like in normal folders and files.
|
||||
- **Windows:**
|
||||
- If you have the Terminal application installed (which is pre-installed in Windows 11), just right-click in the Explorer folder and choose *Open in Terminal*.
|
||||
- If you don’t have the Terminal application installed, press Shift while right-clicking and choose *Open PowerShell window here*.
|
||||
- **Mac:** Right-click on the folder in the path bar of the Finder and choose *Open in Terminal*.
|
||||
|
||||
Now you can create a local copy of the repo by using a command in the command line.
|
||||
Now, insert the following command and run it by pressing Enter.
|
||||
|
||||
### On Windows
|
||||
|
||||
Open the Windows explorer and go to a folder where you would like to out the copy. Open the context menu in the folder while pressing `Shift` and select *Open PowerShell here* from the list.
|
||||
|
||||
|
||||
|
||||
Then run
|
||||
|
||||
```shell script
|
||||
```shell
|
||||
git clone https://github.com/elyukai/optolith-data.git
|
||||
```
|
||||
|
||||
This will create a new folder named `optolith-data`, which contains the repo.
|
||||
This will create a new folder named `optolith-data`, which contains the repo. You can rename the folder afterwards to whatever name you prefer.
|
||||
|
||||
If you want to give the folder a new name, instead use
|
||||
**Warning:** Don’t put this folder inside a folder synced to a cloud service, like iCloud, OneDrive or Dropbox. They usually don’t work well with large amounts of small files, so it’s best to keep it separate. Git itself is already the syncing tool, in the end.
|
||||
|
||||
```shell script
|
||||
git clone https://github.com/elyukai/optolith-data.git folder
|
||||
Move into the folder by running
|
||||
|
||||
```shell
|
||||
cd optolith-data
|
||||
```
|
||||
|
||||
`folder` is the new folder's name.
|
||||
(change the folder name if you renamed it before). Then run
|
||||
|
||||
If you want to copy the repo into the current folder without an extra subdirectory, instead use
|
||||
|
||||
```shell script
|
||||
git clone https://github.com/elyukai/optolith-data.git .
|
||||
```
|
||||
|
||||
**Warning:** Don't put this folder inside a folder synced to a cloud service, since a lot of tiny files will not work with it and may crash your service.
|
||||
|
||||
### On Mac
|
||||
|
||||
Open the finder and go *to the parent folder* of a folder where you would like to put the copy. Open the terminal, type `cd` and then drag the folder you want the repo in into the terminal. This will insert the path to the folder. It should roughly look like
|
||||
|
||||
```shell script
|
||||
cd ~/path/to/folder
|
||||
```
|
||||
|
||||
The space between `cd` and the folder path is important!
|
||||
|
||||
Then run
|
||||
|
||||
```shell script
|
||||
git clone https://github.com/elyukai/optolith-data.git
|
||||
```
|
||||
|
||||
This will create a new folder named `optolith-data`, which contains the repo.
|
||||
|
||||
If you want to give the folder a new name, instead use
|
||||
|
||||
```shell script
|
||||
git clone https://github.com/elyukai/optolith-data.git folder
|
||||
```
|
||||
|
||||
`folder` is the new folder's name.
|
||||
|
||||
If you want to copy the repo into the current folder without an extra subdirectory, instead use
|
||||
|
||||
```shell script
|
||||
git clone https://github.com/elyukai/optolith-data.git .
|
||||
```
|
||||
|
||||
## Install Node.js and relevant modules
|
||||
|
||||
Install the *Current* version of [Node.js](https://nodejs.org/). Then navigate to your cloned folder in the command line, if you are not already inside the correct folder. You can use `cd folder` to move inside `folder`. Then run
|
||||
|
||||
```shell script
|
||||
```shell
|
||||
npm i
|
||||
```
|
||||
|
||||
This will install the database configuration, which is necessary to let Visual Studio Code help you enter or change data.
|
||||
|
||||
## Install and configure an editor
|
||||
|
||||
Follow the [Setting Up an Editor guide](./Setting-Up-an-Editor.md).
|
||||
to install the database configuration and other related modules, so you can check your work and also get better help from the editor.
|
||||
|
||||
## Begin your Work
|
||||
|
||||
To start working on a new feature you need to create a new *branch*.
|
||||
To start working on a new feature you need to create a new **branch**.
|
||||
|
||||
*Branches* are a core feature of Git. A branch represents a special development status or direction. Branches build up on each other. You can branch off from an existing branch, but you can also merge a branch into another branch. The default branch is called `develop` – usually it is called `master` but the `master` branch in this repo has a different meaning. The `develop` branch is where all contributions are merged, and it is also directly reflected in the newest prereleases of Optolith.
|
||||
**Branches** are a core feature of Git. A branch represents a special development status or direction. Branches build upon each other. You can branch off from an existing branch, but you can also merge a branch into another branch. The default branch is called `develop` – usually it is called `main` but the `main` branch in this repo has a different meaning. The `develop` branch is where all contributions are merged, and it is also directly reflected in the newest prereleases of Optolith.
|
||||
|
||||
**At the time of writing, the Optolith version with the new database has not been finished and thus branch names differ from what you read here! The branch you should base off and merge into is called `feature/schema-rework-ama3` instead of `develop`!**
|
||||
|
||||
To start contributing to a specific area and thus to create a new branch, you need to click on the active branch you are currently on in the status bar of VSCode. Make sure you are currently on the `develop` branch.
|
||||
|
||||
@@ -113,15 +62,17 @@ We're going to create a new branch via `Create new branch...`. The name of the b
|
||||
- If you want to fix an issue, prefix the branch name with `fix/`, e.g. `fix/moa3-source-refs`.
|
||||
- If you want to add a new feature, e.g. add a section of a new book, prefix the branch name with `feature/`, e.g. `feature/moa3-spells`
|
||||
|
||||
The branch name should also relate to the name of the issue you want to work on and you also need to make sure it is not blocked by the work of others (see [Project Management](./Project-Management.md) for more details on managing work for all contributors) and assigned to yourself.
|
||||
|
||||
Type it into the next input field and hit enter.
|
||||
|
||||
|
||||
|
||||
Now the active branch in the status bar should be what you just typed in. You created your first branch! Next to the branch name will be the symbol for an unpublished branch. You can click it, and then it will be uploaded to GitHub.
|
||||
|
||||
**Note:** You can and should create multiple branches if you are working on multiple areas at once. You can always switch between them. They are independent of each other.
|
||||
**Note:** You can and should create multiple branches if you are working on multiple areas at once. You can always switch between them. They are independent of each other. Just make sure to **always** branch off the `develop` to keep them independent!
|
||||
|
||||
Now you can start editing the files. Even though this is called *repo* just use it as a normal file system! There are just some advantages over a default file system – because you can save versions!
|
||||
Now you can start editing the files. Even though this is called a *repository* it’s just a simple folder with files! There are just some advantages over a default file system – because you can save versions!
|
||||
|
||||
## Check out your current work
|
||||
|
||||
@@ -129,7 +80,7 @@ You can see all changes made in the Git tab.
|
||||
|
||||
|
||||
|
||||
In the beginning, this tab will not list any changes – because you haven't done anything yet!
|
||||
In the beginning, this tab will not list any changes – because you haven’t done anything yet!
|
||||
|
||||
Once you change something (and save it) it will be shown here.
|
||||
|
||||
@@ -157,7 +108,7 @@ Now your list of changes will be clean. Instead, next to the active branch in th
|
||||
|
||||
|
||||
|
||||
With *push* and *pull* you can *push* new commits from your local repo to the online repo, or you can *pull* new commits from the online repo into your local repo.
|
||||
With *push* and *pull* you can *push* new commits from your local repo to the online repo, or you can *pull* new commits from the online repo into your local repo. This way you can also work on a single branch on multiple machines and sync your work between them.
|
||||
|
||||
VSCode does both operations automatically if you click on the counter (the sync functionality is also available without the counter; sometimes VSCode does not update the counter, so you have to click on the sync icon).
|
||||
|
||||
@@ -165,17 +116,17 @@ Now your commit is online. Let's check it out.
|
||||
|
||||
## Working with GitHub
|
||||
|
||||
In the *Code* tab on the repo's page is an option to switch branches. Clicking on that will show a list of all branches that are available online. At the time of writing there are exactly two branches – the `master` and my own `test` branch.
|
||||
In the *Code* tab on the repo's page is an option to switch branches. Clicking on that will show a list of all branches that are available online.
|
||||
|
||||
|
||||
|
||||
Switch to your branch. It will now suggest creating a pull request.
|
||||
Select your branch. It will now suggest creating a pull request.
|
||||
|
||||
|
||||
|
||||
### Create a Pull Request (PR)
|
||||
|
||||
A *Pull Request* (PR) is a request to merge the new commits from a certain branch into another branch – which is what you want: You want to merge your changes into the main development branch.
|
||||
A **Pull Request** (PR) is a request to merge the new commits from a certain branch into another branch – which is what you want: You want to merge your changes into the main development branch.
|
||||
|
||||
Click on *Compare & pull request*.
|
||||
|
||||
@@ -191,16 +142,22 @@ Example:
|
||||
|
||||
|
||||
|
||||
You'll get notified per e-mail if there are any comments and once you're done and your changes are approved, I will merge your PR. You don't need to do anything else then.
|
||||
You'll get notified per e-mail if there are any comments and once you're done and your changes are approved, your PR will be merged. Don’t merge the PR on your own!
|
||||
|
||||
*Please note that pull requests update if you push more commits to GitHub, so please don't close your already created pull requests. This way we can keep track of the changes and discuss them!*
|
||||
|
||||
## Continue your work
|
||||
|
||||
To start on a new feature, create a new branch as explained before. But you need to make sure that you branch off from `develop` and that there are no commits to pull! If you switch to `develop` and the sync indicator says there are one or more changes to pull (incoming changes) you need to sync first! Only then you should create a new branch. It is recommended to sync the `develop` branch in any case. You also need to make sure that the database configuration is up-to-date, since that might change in other commits to that branch. To do that, simply run `npm i` in the command line again.
|
||||
If more work is needed, just continue to work on your branch and create and push more commits. To start on a new feature, create a new branch as explained before. But you need to make sure that you branch off from `develop` and that there are no commits to pull! If you switch to `develop` and the sync indicator says there are one or more changes to pull (incoming changes) you need to sync first! Only then you should create a new branch. It is recommended to sync the `develop` branch in any case. You also need to make sure that the database configuration is up-to-date, since that might change in other commits to that branch. To do that, simply run `npm i` in the command line again.
|
||||
|
||||
## Summary
|
||||
## TL;DR
|
||||
|
||||
- Create a separate branch for each issue and always branch off from `develop`.
|
||||
- Assign yourself to the issue you’re working on.
|
||||
- If you realize you won’t have time to finish the issue, please unassign yourself, so that others can work on it.
|
||||
- Don’t merge PRs yourself.
|
||||
|
||||
## Continue Reading
|
||||
|
||||
- [Insertion Workflow](./Insertion-Workflow.md) or [Translation Workflow](./Translation-Workflow.md)
|
||||
-
|
||||
|
||||
+4
-2
@@ -2,13 +2,15 @@
|
||||
|
||||
Welcome to Optolith Static Source Data Documentation!
|
||||
|
||||
This Wiki will cover a lot of questions you may have. Let's dive in!
|
||||
This documentation will cover a lot of questions you may have. Let's dive in!
|
||||
|
||||
## Tutorials
|
||||
|
||||
- [Introduction](./Introduction.md)
|
||||
- There are some [Prerequisites](./Prerequisites.md) you need to meet before you can work on Optolith – but don’t worry, it’s neither much nor difficult!
|
||||
- [Project Management](./Project-Management.md) describes where you can find project management resources and how you can integrate yourself to make sure others know about your work.
|
||||
- [Git Workflow](./Git-Workflow.md) is a tutorial for Git and how we use Git. You don't need to have any experience with Git or coding in general, but if you have, you'll get through it way faster!
|
||||
- [Setting Up an Editor](./Setting-Up-an-Editor.md) ... there's nothing else to say what it covers.
|
||||
- [Setting Up Visual Studio Code](./Setting-Up-Visual-Studio-Code.md) ... there's nothing else to say what it covers.
|
||||
- [Insertion Workflow](./Insertion-Workflow.md) is a guide on how to start inserting new content, what you need to know and watch out for.
|
||||
- [Translation Workflow](./Translation-Workflow.md) is a guide on how to start translating existing content, what you need to know and watch out for.
|
||||
- [Testing](./Testing.md) tells you how you can test your work.
|
||||
|
||||
+10
-10
@@ -1,6 +1,6 @@
|
||||
# Insertion Workflow
|
||||
|
||||
This guide covers how you can get started inserting new content into Optolith as well as some best practises we discovered over the past years. (Feel free to tell us yours!)
|
||||
This guide covers how you can get started inserting new content into Optolith as well as some best practices we discovered over the past years. (Feel free to tell us yours!)
|
||||
|
||||
**Note:** If you want to *translate* existing content, please check out [Translation Workflow](./Translation-Workflow.md) instead.
|
||||
|
||||
@@ -10,13 +10,11 @@ First, let's get into some basics.
|
||||
|
||||
### Repository File Structure
|
||||
|
||||
There are three folders used for static data: `/Data`, `/Templates` and `/Schema`.
|
||||
There are two folders used for static data: `/Data` and `/Templates`.
|
||||
|
||||
The `/Data` folder contains another set of folders as well as a `SupportedLanguages.yaml`, which contains all languages that *should be available* in Optolith. Each folder in `/Data` contains all entries of a specific type.
|
||||
The `/Data` folder contains another set of folders, where each folder contains all entries of a specific type. The `Locales` folder contains all languages Optolith *should* be available in.
|
||||
|
||||
While `/Data` holds all actual contents, `/Schema` contains structural definitions (schemes) for each subfolder in `/Data` about how a file should look like. Additionally, `/Schema` contains some utility schema files that are used by multiple main schemes.
|
||||
|
||||
`/Templates` comes as the bridge in between the previous two: prepared forms to fill out, matching the names of the schemes and the respective folder in `/Data`, simplify adding new content.
|
||||
`/Templates` contains “empty” entry files that match the folder name in `/Data` and that can be copied and filled out to simplify adding new content.
|
||||
|
||||
### Editor Validation
|
||||
|
||||
@@ -32,7 +30,7 @@ Each entry has its own file, which contains both the language-independent values
|
||||
|
||||
Now you've got some basic knowledge. But how do you actually insert new data?
|
||||
|
||||
I would recommend to check out existing data first to understand what is does. Take a data file and open the corresponding reference (~~either~~ the schema file ~~or the [type reference](./Entities), although the type reference is way easier to read if you are not used to JSON schema files~~) and then see if you understand what happens. If you have any problems, feel free to ask for help on the Discord server! Then you'll have fewer problems and I can improve the documentation!
|
||||
I would recommend to check out existing data first to understand what is does. Take a data file and open the corresponding reference (either the schema file or the [type reference](./Index-of-Types.md), although the type reference is way easier to read if you are not used to JSON schema files) and then see if you understand what happens. If you have any problems, feel free to ask for help on the Discord server! Then you'll have fewer problems and I can improve the documentation!
|
||||
|
||||
Also, don't start with complex entries! Advantages, disadvantages, special abilities and professions are the most complex entries. Try adding spells or cantrips instead!
|
||||
|
||||
@@ -44,11 +42,13 @@ Always feel free to ask for reviews or hints on the Discord server, if you feel
|
||||
2. Search for an entity type group with **only unassigned** issues.
|
||||
3. Work on the listed issues from top to bottom.
|
||||
|
||||
See [Project Management](./Project-Management.md) for more details on managing work for all contributors.
|
||||
|
||||
## What to watch out for
|
||||
|
||||
### Duplicates
|
||||
|
||||
It is important to always check for duplicates. They may be entries with the same name but different parameters, though. In those cases, please tell me via Discord or in the pull request on GitHub.
|
||||
It is important to always check for duplicates. There may be entries with the same name but different parameters, though. In those cases, please tell me via Discord or in the pull request on GitHub.
|
||||
|
||||
### File Names
|
||||
|
||||
@@ -64,7 +64,7 @@ Entries might span multiple pages. In those cases, use `firstPage` **as well as*
|
||||
|
||||
### New Applications and Uses
|
||||
|
||||
Skills may get *New Applications* and *Uses* from advantages or special abilities. Those need to be registered at the advantage or special ability or one of its select options using the `skillApplications` and `skillUses` properties, otherwise it will not be available in the library entry as well as for other entries like Skill Specialization.
|
||||
Skills may get *New Applications* and *Uses* from advantages or special abilities. Those need to be registered at the advantage or special ability or one of its select options using the `skillApplications` and `skillUses` properties, otherwise it will not be available in the library entry as well as for other entries like *Skill Specialization*.
|
||||
|
||||
### Missing Punctuation
|
||||
|
||||
@@ -72,4 +72,4 @@ From time to time, the source you are transferring into the database has small f
|
||||
|
||||
## Recommendations
|
||||
|
||||
To search for entry identifiers, I highly recommend global search (in VSCode: the search icon in the left bar or `Ctrl+Shift+F`). If you start the beginning of the entry names with a `"`, you'll get more accurate search results. If you know the English name of an entry, or you are searching for an identifier of a specific group, you can press `Ctrl+P` (in VSCode) and type in the identifier as well as the group, separated by a space. Since the entries always have their identifier and their English name as the filename and the group as the folder name, you can find them pretty easy that way.
|
||||
To search for entry identifiers, I highly recommend global search (in VSCode: the search icon in the left bar or `Ctrl+Shift+F`). If you start the beginning of the entry names with a `"`, you'll get more accurate search results. If you know the English name of an entry, or you are searching for an identifier of a specific group, you can press `Ctrl+P` (in VSCode) and type in the identifier as well as the group, separated by a space. Since the entries always have their identifier and their English name (German name if no English translation is available yet) as the filename and the group as the folder name, you can find them pretty easy that way.
|
||||
|
||||
+13
-9
@@ -1,24 +1,28 @@
|
||||
# Introduction
|
||||
|
||||
Welcome! This section gives you an overview of how you can help out working on the database and what you need to accomplish that.
|
||||
Welcome and thank you for considering to contribute to Optolith! This section gives you an overview of how you can help out working on the database and what you need to do it.
|
||||
|
||||
First, it's important to know that you won't need *any* programming knowledge for this. You also don't need any specific database knowledge, since Optolith uses a custom database.
|
||||
First, it's important to know that you won't need *any* programming knowledge for this. You also don't need any specific database knowledge, since Optolith uses a custom flat-file database. And if you’re afraid of doing any damage: You can’†! Git makes it easy to travel back in time and the most important areas are protected so you couldn’t do anything even if you tried! So don’t worry about making any mistake!
|
||||
|
||||
You *do* need some tools to be able to contribute:
|
||||
|
||||
- A GitHub account, since the database is stored on GitHub and also project management is done there
|
||||
- Git, which is a version control management software
|
||||
- Node.js, which is a software for running JavaScript, but we only need to get the package manager from its ecosystem
|
||||
- a plain text editor, Visual Studio Code is recommended
|
||||
- A **GitHub account**, since the database is stored on GitHub and also project management is done there
|
||||
- **Git**, which is a version control management software
|
||||
- **Node.js**, which is a software for running JavaScript, but we only need to get the package manager from its ecosystem
|
||||
- A **plain text editor**, Visual Studio Code is recommended
|
||||
|
||||
More details about all those prerequisites are outlined on a [dedicated page](./Prerequisites.md).
|
||||
For more details about all those prerequisites, check out the [Prerequisites page](./Prerequisites.md). *Note that often there will be multiple ways or tools to achieve the same thing. If you’re familiar with the topic, feel free to use the tools or ways you prefer; the guides you’ll find here will describe a single way to keep it simple.*
|
||||
|
||||
Although you won't need any programming knowledge, you'll need to use a terminal in specific situations. There are only specific commands you need to execute and following tutorial will explain all of them.
|
||||
|
||||
What else do you need? Well, time. Entering data can be quite time-consuming, even for people familiar with it. It also helps if you have a good knowledge of *The Dark Eye* rules, since then the database will be more self-explaining, so it will be easier to understand what to do.
|
||||
What else do you need? Well, time. Entering data can be quite time-consuming, even for people familiar with it. It also helps if you have a good understanding of *The Dark Eye* rules. It will make the database more self-explanatory and thus easier to work with.
|
||||
|
||||
The database is closed source due to licensing reason. If you want to contribute, please contact @elyukai, he will get you access to everything you need. To start learning how to contribute to the database, starting with the [Git Workflow](./Git-Workflow.md) and continuing with either [Insertion Workflow](./Insertion-Workflow.md) or [Translation Workflow](./Translation-Workflow.md) – depending on if you insert completely new data or only translations of existing data – is the recommended way.
|
||||
The database is closed source due to licensing reason. If you want to contribute, please contact @elyukai, he will get you access to everything you need. To start learning how to contribute to the database, start with the [Project Management](./Project-Management.md) and [Git Workflow](./Git-Workflow.md) guides and continue with either [Insertion Workflow](./Insertion-Workflow.md) or [Translation Workflow](./Translation-Workflow.md) – depending on if you insert completely new data or only translations of existing data.
|
||||
|
||||
Checkout [Project Management](./Project-Management.md) to get an overview of the available resources for project management in Optolith. You’ll find details in the respective workflow guides.
|
||||
|
||||
If you have any questions, feel free to reach out on GitHub Discussions or [Discord](https://discord.gg/wfdgB9g)!
|
||||
|
||||
## Continue Reading
|
||||
|
||||
- [Prerequisites](./Prerequisites.md)
|
||||
|
||||
+12
-3
@@ -4,19 +4,24 @@ You'll need a few programs to help inserting, changing or translating content.
|
||||
|
||||
## Code Editor
|
||||
|
||||
You'll need a plain text editor if you work on the Optolith database. If you have no previous coding experience, it is recommended to install [Visual Studio Code](https://code.visualstudio.com/), since all tutorials work with it and there are some configurations for it in the database as well.
|
||||
You'll need a plain text editor if you work on the Optolith database. If you have no previous coding experience, it is recommended to install [Visual Studio Code](https://code.visualstudio.com/), since all tutorials work with it and there are some configurations for it in the database as well. To make the most out of it, make sure to follow the [setup guide for Visual Studio Code](./Setting-Up-Visual-Studio-Code.md).
|
||||
|
||||
## Git
|
||||
|
||||
[Git](https://git-scm.com/) is a *source control management* software (SCM). Using Git, you can keep track of changes to your files, so that you always know what happened in the past. Changes in a *repository* (short *repo*) are applied using *commits*, which act like save points, so you can always get back and forth between them, if needed. Since changes are usually not applied in a linear way (not everyone is working directly on the same version status), you can create *branches*. This way, you can branch off a certain commit, work on that independently from others, and once you're ready, you can *merge* your changes back. There's always at least one branch in a repository you can branch off and merge into. In our workflow, this is usually done using **pull requests** (PRs) on GitHub.
|
||||
|
||||
### Install GIt
|
||||
### Install Git
|
||||
|
||||
You can simply confirm all choices, although it is recommended to choose *Visual Studio Code* as an editor if you have not had any previous coding experience, since this is the editor all tutorials work with.
|
||||
|
||||
## GitHub
|
||||
|
||||
You'll need a [GitHub](https://github.com/) account to contribute, since the data is hidden in a private repository due to licensing reasons. GitHub hosts all different Git repositories for Optolith and also provides solutions for bug tracking and tracking other issues and requests.
|
||||
You'll need a [GitHub](https://github.com/) account to contribute, since the data is hidden in a private repository due to licensing reasons and you need to be able to assign yourself to issues. GitHub hosts all different Git repositories for Optolith and also provides solutions for bug tracking and tracking other issues and requests.
|
||||
|
||||
You’ll need access to the following repositories:
|
||||
|
||||
- [`optolith-client`](https://github.com/elyukai/optolith-client) for project management
|
||||
- [`optolith-data`](https://github.com/elyukai/optolith-data) for inserting new data
|
||||
|
||||
## Node.js with NPM
|
||||
|
||||
@@ -25,3 +30,7 @@ You'll also need [Node.js](https://nodejs.org/en/), since (most of) the differen
|
||||
### Install Node.js
|
||||
|
||||
You can confirm the default choices. Especially, you'll *not* need to `Install additional tools for Node.js` if asked.
|
||||
|
||||
## Continue Reading
|
||||
|
||||
- [Project Management](./Project-Management.md)
|
||||
|
||||
@@ -1,8 +1,16 @@
|
||||
# Project Management
|
||||
|
||||
The work on Optolith is managed across different places on GitHub. This way, it can be viewed in different ways, depending on your needs.
|
||||
The work on Optolith is managed across different places on GitHub. This way, it can be viewed in different ways, depending on your needs. The issues – the base blocks of project management – are all in the public `optolith-client` repository, so that everyone can see the work progress – and you will need special access to participate in project management.
|
||||
|
||||
- **[Client Issues](https://github.com/elyukai/optolith-client/issues):** The `optolith-client` repository contains all bugs, feature requests and other kinds of improvements.
|
||||
- **[Publications](https://github.com/users/elyukai/projects/4/views/1):** This board is an overview of the general progress of publications in Optolith. It is never directly used.
|
||||
- **[Missing Entries by Category](https://github.com/users/elyukai/projects/6/views/1):** This board shows unfinished entries from books, grouped by entity type. All listed issues are sorted in chronological order and need to be worked on from top to bottom. Only a single person must work in an entity type group at the same time to prevent identifier clashes.
|
||||
- **[Database Schema V2](https://github.com/users/elyukai/projects/3/views/1):** This board contains an overview of all missing work needed to finish the V2 database. You may not see the board items if you do not have access to the database repository.
|
||||
|
||||
Most of the time, you’ll be using the **[Missing Entries by Category](https://github.com/users/elyukai/projects/6/views/1)** board. If you want to start contributing, search for a column **where nobody is assigned to any of the listed issues** and assign yourself to the first issue of the column. Issues **must** be worked on **from top to bottom** (in chronological order, that is, sorted by publication date of the associated book) and you can’t work on issues in a column with others at the same time to prevent collisions.
|
||||
|
||||
If you realize you don’t have enough time to contribute more, it is of course not a problem. But **please unassign yourself** from all issues and add comments to describe your work so far and which branch(es) you used – so that others can continue where you stopped.
|
||||
|
||||
## Continue Reading
|
||||
|
||||
- [Git Workflow](./Git-Workflow.md)
|
||||
|
||||
@@ -1,24 +1,10 @@
|
||||
# Setting Up an Editor
|
||||
# Setting Up Visual Studio Code
|
||||
|
||||
Editing the YAML files with a proper editor will make it much easier to work with. You don't need any coding knowledge or editor knowledge, but it will help you a lot.
|
||||
|
||||
I recommend [Visual Studio Code](https://code.visualstudio.com) (VSCode), since it's lightweight and very easy to use. I will use it for all tutorials here. Bonus: I also use it to work on Optolith, so the configuration you need is already present.
|
||||
It is recommended to use [Visual Studio Code](https://code.visualstudio.com) (VSCode), since it's lightweight, very easy to use and important configuration is already present.
|
||||
|
||||
## 1. Install an editor
|
||||
|
||||
Install *Visual Studio Code* from the page linked above. (or another editor of your choice). I'd recommend to check *Add "Open with Code" to file context menu* and *Add "Open with Code" to directory context menu*.
|
||||
|
||||
## 2. Open the Project
|
||||
|
||||
*This step assumes you either cloned the repo by following the [Git Workflow](./Git-Workflow) or got the project folder from me.*
|
||||
|
||||
If you checked the context menu additions during the installation process, you can open the context menu of the project folder and select *Open with Code*. Otherwise you can open VSCode and select the repo folder via `File > Open Folder...`. *It is important to open the project folder!*
|
||||
|
||||
|
||||
|
||||
This should be the initial folder structure you can check out. `Data` contains all data, while `Schema` contains the schemes for the data files.
|
||||
|
||||
## 3. Activate Schema validation
|
||||
## Activate Schema validation
|
||||
|
||||
*Schemes* validate files and the editor can highlight errors so you can easily fix them. To get schema validation in VSCode, you need to install the YAML extension from RedHat.
|
||||
|
||||
@@ -26,12 +12,22 @@ This should be the initial folder structure you can check out. `Data` contains a
|
||||
|
||||
The configuration for the VSCode YAML extension is already present, so you don't need to configure the schemes yourself.
|
||||
|
||||
## 4. Done!
|
||||
## Open the Project
|
||||
|
||||
*This step assumes you either cloned the repo by following the [Git Workflow](./Git-Workflow) or got the project folder on another way.*
|
||||
|
||||
If you checked the context menu additions during the installation process, you can open the context menu of the project folder and select *Open with Code*. Otherwise you can open VSCode and select the repo folder via `File > Open Folder...`. *It is important to open the project folder!*
|
||||
|
||||
|
||||
|
||||
This should be the initial folder structure you can check out. `Data` contains all data, while `Schema` contains the schemes for the data files.
|
||||
|
||||
## Done!
|
||||
|
||||
Now you should see explanations of fields if you hover over them:
|
||||
|
||||
|
||||
|
||||
You'll also get autocompletion if you start typing or press `Ctrl+Space` (Windows, Linux) or `Cmd+Space` (macOS):
|
||||
You'll also get autocompletion if you start typing or press `Ctrl+Space`:
|
||||
|
||||
|
||||
@@ -4,6 +4,20 @@ This small guide covers how to test changes to the data with Optolith.
|
||||
|
||||
You can (and probably should) check if what you worked on, first of all, is valid and, second, does what you expect.
|
||||
|
||||
## Validation
|
||||
|
||||
Simply run
|
||||
|
||||
```shell
|
||||
npm test
|
||||
```
|
||||
|
||||
in the terminal in the repository folder. It will output if files have errors and what these errors are.
|
||||
|
||||
This will do structural testing, i.e. validate the files using the JSON Schemes that already help you catch errors in the editor, as well as semantic testing, which includes checking if referenced entries actually exist and other checks that cannot be done using simple JSON Schema validation.
|
||||
|
||||
## Manual Testing
|
||||
|
||||
To do that, you'll need a prerelease version. You'll get a link either on the Discord server or in an e-mail. If you don't have a prerelease installed yet, install it now. It will be installed separately from your stable installation and it will also not affect your characters in your stable, so you're pretty safe to do that.
|
||||
|
||||
Go to the installation folder and then in the `resources/app.asar.unpacked/app/Database`. You'll notice there are a lot of folders that are in the `Data` folder of the project as well. Copy the files and folders from the `Data` folder into `resources/app.asar.unpacked/app/Database` so they match the existing folder structure. Then, (re)start the Optolith prerelease. You should now see your changes and can try them out. If the source files are invalid, there'll be an alert and you won't see the characters list.
|
||||
|
||||
@@ -12,49 +12,44 @@ This page aims at people who want to translate existing content into another, po
|
||||
|
||||
*This only applies if you want to add a new language.*
|
||||
|
||||
Open the `Data/SupportedLanguages.yaml` file and add a new entry. The new entry consists of:
|
||||
Add a new language file in `/Data/Locales`. The new entry consists of:
|
||||
|
||||
- An *IETF BCP 47 language tag*. Such a language tag is formatted so that in `xx-YY` the `xx` are the language code (e.g. `de` for German or `nl` for Dutch) and the `YY` are the region code (e.g. `DE` for Germany and `BE` for Belgium). If you're not sure what to use, please ask.
|
||||
- An *IETF BCP 47 language tag*. Such a language tag is formatted so that in `xx-YY` the `xx` are the language code (e.g. `de` for German or `nl` for Dutch) and the `YY` are the region code (e.g. `DE` for Germany and `BE` for Belgium). If you're not sure what to use, please ask. This tag is also used as the file name.
|
||||
- The name of the language and associated region in the respective language.
|
||||
|
||||
Now Optolith knows of that addional language and will be able to automatically infer it from you system (if you chose *System language*) and it will provide it as an option in the settings as well.
|
||||
Now Optolith knows of that additional language and will be able to automatically infer it from your system (if you chose *System language*) and it will provide it as an option in the settings as well.
|
||||
|
||||
Also, create a new folder in `Data` which name is the language tag of the new language.
|
||||
You also need to add a new UI file in `/Data/UI`, which contains all translations for the user interface. The easiest way is to copy an existing file, use the new language tag as the file name and adjust all contents.
|
||||
|
||||
## 1. Copy files/entries
|
||||
## 1. Update entries
|
||||
|
||||
Copy the files you want to translate if they are not present in your language's folder from the folder of the language you want to translate from. Otherwise go into the files where you want to translate entries from and copy/paste those entries into the files in your language folder.
|
||||
Identify which entries need to be updated. If you just started a new language, these will be a lot of basic entries like attributes, skills and so on.
|
||||
|
||||
## 2. Update entries
|
||||
|
||||
The follwing two parts should be followed at the same time, so you only need to go through every list of entries once.
|
||||
|
||||
### 2.1 Replace texts
|
||||
|
||||
Replace *all* text values (those to the right of the colons) with the translated strings.
|
||||
All entries use so-called *locale maps* that provide different translations for an entry. In almost all cases they can be found at a `translations` property. Simply copy a language that’s already present, adjust the key (which is the language tag) and replace *all* text values (those to the right of the colons) with the translated strings.
|
||||
|
||||
You may notice some special characters, usually in *block texts*. These are *Markdown syntax*. You can find more information about that on the [Markdown page](./Markdown).
|
||||
|
||||
If your texts include formatting like italic or bold text, please also apply that to the texts in Optolith via Markdown.
|
||||
|
||||
### 2.2. Update books and book references
|
||||
Note that an entry may contain multiple `translations` properties. This may be because an entry can contain sub-entries. For example, a skill has applications, which all contain their own `translations` property.
|
||||
|
||||
Optolith checks if an entry can be used by their occurrences in publications. First, you need to have the new books available in the `Books.yaml`, so you know which `id`s they have (for the currently available languages, the publisher's own publication id was used, like `US25001` for the German Core Rules or `LDR1` for French Core Rules). Then, you can update the references in the `src` attribute. Please remove the old ones, since they reference books from a different language.
|
||||
### Availability by Publication
|
||||
|
||||
If an entry spans a range of pages, please add a `lastPage` in addition to the `firstPage`. If there are multiple, not consecutive pages, you can just add a second `src` entry. Why adding mutliple entries? The publication references will be available to the Optolith users as well. If you provide all pages, they can check out the publications more easily.
|
||||
Optolith checks if an entry can be used by their occurrences in publications. First, you need to provide the `translations` for the books already available in other languages. Then, you can update the references in the `src` attribute. They work like `translations`, but are called `occurrences`.
|
||||
|
||||
## 3. Test your work
|
||||
If an entry spans a range of pages, please add a `last_page` in addition to the `first_page`. If there are multiple, not consecutive pages, you can just add a second `src` entry. Why adding multiple entries? The publication references will be available to the Optolith users as well. If you provide all pages, they can check out the publications more easily to find related content in the respective publication.
|
||||
|
||||
## 2. Test your work
|
||||
|
||||
See the [Testing guide](./testing) for more information.
|
||||
|
||||
## 4. Commit
|
||||
## 3. Commit
|
||||
|
||||
You can now follow the [Git Workflow](./Git-Workflow) to commit and push the changes (if you're familiar with Git, you won't need that, of course).
|
||||
|
||||
## Notes
|
||||
|
||||
- **New Applications/Uses:** If you add advantages or special abilities that add *new applications* or *uses* to skills, make sure to check for the correct `id` of that application/use in more complete languages and then add the new application or use to the skill entry.
|
||||
- `UI.yaml`: This is the only files that’s kind of that “key=value” schema often used for translation files. Every key is required, but if there are terms you don’t have translations for currently, you can leave them in English, they will not be shown (since they probably won’t be used by any entry then). Also, you may notice some numbers in curly braces like “{0}”. These are placeholders for values that will be inserted by Optolith; what each value represents should be written in a comment above that text.
|
||||
- **UI:** These are the only files that kind of use that “key=value” schema often used for translation files. Every key is required, but if there are terms you don’t have translations for currently, you can leave them in English, they will not be shown (since they probably won’t be used by any entry then). Also, you may notice some numbers in curly braces like “{0}”. These are placeholders for values that will be inserted by Optolith; what each value represents should be written in a comment above that text. Some keys may also use *plural rules* and split into subkeys named `zero`, `one` or `other`. These use the [Plural Rules](https://cldr.unicode.org/index/cldr-spec/plural-rules) defined by the Unicode Common Locale Data Repository (CLDR). Please check it out to identify which keys to use for your language. Sometimes, not all keys available for your language are needed, but if you miss one, the `other` key is always used as a fallback.
|
||||
- **Comments:** Feel free to add comments to any YAML file if you need them, you just need to write a `#` and the part of the line after that can be used as a comment.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -4,7 +4,7 @@ If you're using the Optolith database for your own project, this page is for you
|
||||
|
||||
Also, if you've worked with the database previously, feel free to share your insights here as well!
|
||||
|
||||
Lastly, please don't forget to credit The Optolith Project, since a lot of work and ❤ went into this database. Thank you! 🥰
|
||||
Lastly, please don't forget to credit The Optolith Project, since a ton of work and ❤ went into this database. Thank you! 🥰
|
||||
|
||||
## Integrate into non-JavaScript environments
|
||||
|
||||
@@ -14,7 +14,7 @@ If you can't support the exact same structure – or it would be way easier to d
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
Optolith follows [semantic versioning](https://semver.org/). This includes character exports and the database; they all share the same version. Since the database schema also targets data contributors, it is stricter than required and thus may fail on changes that are not considered breaking.
|
||||
Optolith follows [semantic versioning](https://semver.org/). This includes character exports and the database; they all share the same MAJOR version. Since the database schema also targets data contributors, it is stricter than required and thus may fail on changes that are not considered breaking.
|
||||
|
||||
### Changes that **are** considered breaking changes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user