Helping with Data Entry
[[TOC]]
This page describes how to help out with the glamourous task of data entry and updating.
The basic principle is simple: you create a local copy of the Pathfinder 2 system, make your edits in Foundry, and then submit your changes. The changes get sanity checked by someone else, and then added into the next release of the system!
The rest of the page describes these steps in more detail, and assume that you have very little technical knowledge, and are using Windows 10.
If you're familiar with git, go read contributing.md, as that has the short version of this page ;).
Forking is as easy as clicking the fork button on the main Foundry page and signing up with a GitLab account if you don't have one. You want to have an actual account, not one you sign in from another service with because you're going to need a password. If you already made one with another service like sign in with Google or GitHub or whatnot just go into your Gitlab account settings and change the password.
You will likely want to set your repository to public, on your fork go to settings -> general -> visibility, and set the fork to be public. If you cannot set up repository mirroring this is the most likely culprit.
You need to install some software first, which will let you download the Pathfinder 2 system and edit it. Download and install these programs:
The next step is to use these bits of software to create your own local version. Start up "git cmd" - if you're on Windows, it should start up in your local user folder, which is fine. Replace the in the following text, type it into the command line, and press enter git clone https://gitlab.com/<yourName>/foundry-vtt---pathfinder-2e.git master
This tells git to go and find the Pathfinder 2e system, and put a copy of it into a folder called 'master'.
You next need to navigate into the newly created folder by typing cd master into git cmd. Once you're in there, type npm ci. This tells the computer to install node package manager, which will be used for the actual editing steps.
Then, using Windows Explorer, go to the same folder. Find and open foundryconfig.example.json. You need to replace PATH_TO_DATA_FOLDER/FoundryVTT with the place that your local version of Foundry is installed. For most people on Windows, that'll be something like C:/Users/YourUserName/AppData/Local/FoundryVTT (make sure to use forward slashes, rather than backward slashes especially if you copy this from Windows Explorer!).
Update the text document, save it as a new copy, and rename it to be foundryconfig.json. This will tell make your local version of Foundry use the Pathfinder 2 you've downloaded, rather than the normal one.
It should look something like this when you're done:
You can open Foundry, and find out where local files are saved by looking at the User Data Path entry in the Configuration tab:
Tip: if you start getting weird error messages later on, a good first step is to repeat npm ci, as it often works to fix things.
Hurrah, you now have a local version of the Pathfinder 2 system that you can edit! Open up git cmd again, and navigate into the master folder.
The Pathfinder 2 system is updated a lot. You need to make sure that your local copy is up-to-date with the 'master' version on the gitlab website. You do this by typing git pull, which means 'go get the new version from the website'. You almost can't do this step too often!
Once you're up-to-date, you need to get the the files set up properly. Do that by typing npm run build into the git cmd program (make sure you're in the master folder). This process can take several seconds.
Now you can open up Foundry! You'll know if the previous steps have worked if you check the version number of the Pathfinder 2 system - it should be something like 1.11.13, while the normal versions will be 1.11.13.12345.
Here's what it should look like:
Go find the compendium you want to edit, and unlock it by right clicking. Then open the compendium and edit the item you want to make changes to directly in the compendium.
If you are adding new items to a compendium create a folder in the items or actors sidebar and create the new item(s) or actor(s)
To save your changes properly, you need to use git cmd. Get back to the master folder, and type in npm run extractPacks spell-effects.db C:\Users\YourUserName\AppData\Local\FoundryVTT\Config\options.json.
"spell-effects.db" should be replaced by the compendium you exported to within Foundry; if the compendium has more than one word in its name, they'll be separate with - instead of spaces. If you've edited more than one compendium, enter the command multiple times, changing the ".db" each time. If your local version of Foundry has a different User Data Path than my example, you'll need to change this text to use your Foundry's location.
Here's an example of a successful extractPacks on the feats.db:
Now comes the final stages to 'push' your changes to the main gitlab website.
Open up git cmd and navigate back to your master folder. You need to tell git to make a 'branch', which is a version of Pathfinder 2 with your changes. Type in git checkout -b [branchname] where [branchname] is whatever you want. Choose something not too long, like "Corrected_Dragons", as you'll need to type it a few more times.
Then you type git add packs/data/* This tells git to put all the edits you've done into the files that will be uploaded onto the website.
At this point, I normally open up git gui, which is another bit of software that git installed. You'll see a lot of files on the right hand side, which are called 'Staged Changes'. These are the documents you'll be uploaded in a few moments. Check them over in case Foundry has decided that you've edited some files that you haven't touched. Press Control-T when you're highlighting a file to 'unstage' it - this gets it out of the way for the next steps.
Here's what gitgui looks like with a load of 'staged changes'. You can also use this programme to select each file and see what's changed in the yellow panel - deleted info is in red, and added info is in greeen:
You need to commit your staged changes next. Type a brief description into the commit message box, and press commit:
Once you have the commit set you can click the push button to push your changes from your computer locally to your fork on gitlab.
Finally, go to the gitlab website and log in, and go to the Pathfinder 2 page. You should see a button near the top, asking you if you want to create merge request - press it! On the next page, create a short title ("Fixing errors in dragons") and a longer description ("Correcting errors in all dragons from Bestiaries 1 and 2"). Press 'Create Merge Request' and you're done.
If your Gitlab account was created after May 2021 you will need to go through additional account verification in order to run the "pipeline", which verifies that the files you are merging is compatible. This process was restricted to require accounts be verified with a credit card (no charge) in order to prevent abuse by bitcoin miners. We, and many other projects on gitlab, have asked for this practice to end.
Adding your changes to the main system is called merging. Before that happens, someone will sanity check your changes. You should get emails about this - sometimes the sanity checker will notice mistakes, or have questions about what you've done. Once those points are addressed, they'll merge your changes - and you'll see them in the next version of the system that gets published!
When you stopped working in git, you were still messing around in your local little version or branch. Next time you want to work, go to the master folder and do git checkout master. This tells git to leave your local sub-version, and go back to the main folder. You'll want to do git pull next and start over from the npm run build step above.
Sometimes, git will complain about you having local files that will be lost. To shut it up, type git stash save and then git stash drop - this saves any left-over files, and then puts them in the bin. This probably isn't very good practise if you're using git properly, but it works for this dummy's guide version :).
To keep your fork up to date you will need to pull down changes from the main repo, which we will refer to as the upstream repo here. To see what you have called it on your local git install run git remote -v and you should see something like this
this will tell you what the names of each repo are. Typically these will be origin and upstream but some installs may differ. To update your fork run these:
git checkout master
git pull upstream master
git rebase upstream/master
Then push the branch (you should not need to make a commit, just push). If you are using Gitlab mirroring (premium feature or grandfathered account) this step can be reduced to simply git checkout master followed by git pull.
Once you're familiar with the above, here's a quick summary of the steps you need to do with git and foundry to make a new branch:
- git checkout -b new_branch
- some work
- git gui
- choose your commits and write a commit message
- commit and push from the gui (easier than terminal)
- git checkout master so the changes you just made don't move onto your next project