Workflow

In general the workflow for the app can be called GitHub based. The app relies on data which is pushed from GitHub and is validated.

A file may go out of sync, but the data is kept in the GitHub repository separated from the code to be available for other implementations and applications.

That is to say, if you do not see your data updated in a few seconds, then please see the validation page and if this does not help, open an issue.

Once you have GitHub installed and the repositories are all up to date you are ready to start.

You will need to make a branch for your changes, or switch to the branch where you want to make those changes. The web is full of tutorials on how to do this. once you are on your branch, and not on the master, you can edit.

Open on your computer the folder where you have cloned the GitHub repository, for example, a BetMas folder on your desktop where you have the Manuscripts folder, which is the cloned repository.

Select the file you want to edit, e.g. EMIP00001.xml. Open the file with Atom or Oxygen or any other XML editing software you like. In Atom, you can also make sure you are on the right branch, just in case. You find more advice in the setup page, for example, to create a project, which will allow you to avoid having always to go back and between from your system and the software.

Following these guidelines, you can edit the file and save it.

GitHub will see the change and if you open it, you will see that it has recorded the changes you made (under the changes tab). When you are ready, you can make sure you have recorded your changes, that your files are valid and then you can commit them to your working branch, leaving a commit message which explains what you have done (i.e. avoid commit messages like 'upd' or 'changes'...). Once you are done with your task you can then make a pull request of your branch. The BM team will review it and merge it into the master branch, and after few seconds from that point, you can eventually check your file in the web application.

After a Pull Request is merged, your branch will be deleted. To create a new one, make sure you are up to date with the main repository, moving to the master branch and fetching the latest changes. Only then create your new working branch if you need to.

Branches are relative to repository, so, if you are working on Manuscripts, Persons and Works, you will need to identify or create a branch to work in for each repository.

Some tasks, like finding the correct ID for a reference or named entity, will need anyway to use the application, unless you prefer to search through the files directly in your editing software.

In very limited and checked cases you might need to create new entries. You need permission to do so via the application. then you can follow the guidance in the new record creation page.

Although it is highly advisable that while encoding you do not concern yourself with "how it will look like" and thus modify unproperly your encoding to feet a specific visualization, there are cases in which you may want to support your editing with a preview of the information you are encoding.

If you wish to use this option, you will need to clone also the BetMas repository from the organization on GitHub: this is where the application code is maintained.

Once you have cloned this repository, make sure to know the absolute location of the directory inside the repository where the application files are stored, e.g. /Users/name/path/BetMas/BetMas/

You will need Oxygen, or another way to run a XSLT transformation locally. In the following steps we assume you are using Oxygen

  1. Open in Oxygen XML the file you want to preview.
  2. Click on Configure Transformation Scenario and click on NEW to create a new scenario. Select XSLT Transformation.
  3. Select as input for XML URL the current file (this is the default option)
  4. Select as input for XSL URL one of the four XSLT which are found in the repository of the application under XSLT, and are called localView*.xslt . the last part of the filename is the type of record you want to preview. You will need one scenario pointing at a different XSLT for each of the record types.
  5. Set the processor to the latest Saxon version available, e.g. PE 9.6.0.7.
  6. Click on parameters, and double click on absolutePathApplication. In the text box which opens copy the absolute path to the application repository cloned on your machine, e.g. /Users/name/path/BetMas/BetMas/ . be sure to include the last / .
  7. Switch to the output panel and set it to save a file with a name with extension ".html" of your choice in a location which is not an official repository, e.g. on your desktop. Select Open in Browser and unselect the option to show as XML in the results view.
  8. Once all is set, click ok to run the transformation. The preview will open in your browser.

For small changes to files, please consider the use of the EDIT button on top of each record. Just hit it, and then click on EDIT in the GitHub file view. Once done, click on Propose Changes making in this way a Pull Request.

Batch editing files

You can find and replace strings or regex patterns throughout the data in Oxygen, for example. Before replacing all, you will be asked if you want to preview. This is always wise and gives you one more occasion to spot check your changes before performing the action. Please, make sure you untick the option to create .bak files - in case you forget, and such files are created, please DO NOT commit them.

In case you have anyway made a mistake, remember that before committing data you can review in Git desktop the changes and discard them if they are wrong. If you have committed, pushed and you realize it was a big mistake, you can revert your commit

If you find a mistake that needs to be corrected over hundreds or more file, make an issue, we will fix it during a data freeze.

Keeping track

To keep track of the workflow we used to refer to a google drive spreadsheet. This workflow is deprecated and discouraged in any way, as the spreadsheet is outdated by two years and should not be used to support any statement about entities in the website. Its historical purpose, and usage to originate the initial batch of data does not justify the redundancy of going back to look into that.

You can use your user page to see what you have done recently or use the latest function to see what is new in the data.

This page is referred to in the following pages

Revisions of this page

  • Pietro Maria Liuzzo on 2018-04-30: first version of guidelines from Wiki