GITHUB

Git is a shared repository, public on the web, where we keep our project files and code. Our organization in GitHub.com contains several repositories, which are just like folders from a user perspective. Here are the files we work on and the documentation, such as guidelines and issue tracking. You will use this to:

1. Keep your files in sync with others

2. Point out issues, problems requests

You will want to be always up to date. Here is what to do:

• After you created and verified your account, you will need to be added to the group. Email the technical lead to get this done.

• Install GitHub Desktop

• Prepare in your computer in a location of your choice a folder called BetMas or any name you will remember

• Open GitHub Desktop

• Login if you aren't automatically logged in and follow the authentication procedure, which involves the generation of a token and will be prompted for you.

• Click "file" on the top left corner

• Select "clone repository"

• If you are already in the group, you will find the Beta Masaheft repository listed there, select the one you want

• When asked where to clone in the form, select the directory you have created before.

• Click CLONE below

• This will create a folder with the same name of the repository in your BetMas folder which is identical to that in GitHub and can be synced with it if you are online.

• repeat the same operation for all other BetaMasaheft repositories which you may need, most typically Authority-Files, Manuscripts, Persons, Places, Repositories and Works

Let's say you have edited a manuscript file from the newly cloned Manuscripts repository or created a new manuscript file. To add a new file to the Manuscripts folder, create a new file in your XML editor and save it to the Manuscripts folder which you have in your BetMas folder.

• Open GitHub Desktop and select the Manuscripts repository on the left

• Before you commit your changes, make sure that you are synced, and that other collaborators to your branch know you are sending this Pull Request: click on "fetch origin" in the upper right corner, and, if there are new commits by others, click on "pull"

• Click the CHANGE tab and you will see that it has recorded the fact that you have added a new file to the folder or modified an existing one in your branch

• Below the list of changes there is a Commit field, where you can enter a name such as "new manuscript ready for review" and a description about what you have done e.g. "entered catalogue entry 1234 from Catalogue X" Please see also this page on revisions history.

• Click commit

• Once it has committed the changes on the top right corner, click SYNC (old version of GitHub Desktop) or PUSH. This will look for anything that has changed online in your current branch and update your files locally, then will upload your file or update the online version from yours.

• N.B. THERE IS NO RISK of data to be overwritten or lost.

• However, under no circumstances do a Force Push to the repository unless advised by the Tech Lead of the project to proceed this way.

Once you are finished with your edits and want to send them live, select your branch and create a new Pull Request. This will merge the changes in your branch to the master branch, and thus make them live in the web application.

Before this can happen a review of the encoding takes place and once this has been successful, the Pull Request is merged by a member of the team into master.

It is always advisable to Sync/fetch the master branch all your repositories before you begin a work session.

The Documentation repository contains two other important parts, besides some code used locally for the project, the Wiki and the Issues

Issues

Let's say something goes wrong. e.g. I cannot see anymore the values from the schema! or the text displayed is the wrong one!. Open an issue for that here and give as much detail as possible.

There are templates provided to guide you in writing a nice and understandable issue.

Atom

You can use Atom to edit files, but to validate and get schema related support (like autocompletion) you will need to install a package.

linter-autocomplete-jing Normally, Atom will install dependencies for you, if it fails to do so, at the moment, the current version of this package needs Java to be installed on your machine, and the following additional packages: busy-signal, intentions, linter, linter-ui-default.

once you have Atom installed, inside Atom, go to settings (or preferences on mac), then click on + install on the left and search the above string.

It will find the package. Click on install and say yes to dependencies installation requests.

You will then see errors messages and will get the autocompletion. it works very well!

Note also that if you open a folder as project in atom, which is a git repository, you will be able to pull and push directly in ATOM, using the Github package which is shipped with it. It is awesome.

Just click on the arrows pointing up and down in the bottom right corner and you will have all in one place.

Oxygen

Oxygen is a text editor which is very smart with XML. Oxygen is designed to help you write XML and it does it wonderfully, with all possible tools to help you in your workflow. Very often you will only use a few of the options provided. Some things you might find useful to know:

You can create a project and add to it your folders, so you can open files from Oxygen directly.

1. click on PROJECT, then on NEW project. Call the file BetMas and save it to your BetMas folder, where you cloned the repositories from GIT.
2. Once created, the project will open in Oxygen in a sidebar on the left (if it doesn't, click on "Project" and "project view" in the upper menu bar).
3. click with the secondary button on the icon of the project and select "add Folder"
4. select the folders in the BetMas folder and add them all.
5. They will appear under the Project icon. Open the manuscripts folder and click on a file to open it.

While editing your file you might start from one existing file, taking it as a model, and always reading and comparing other files. Oxygen has several helpful features that will facilitate your work:

1. Once you start typing a name of an element, Oxygen will suggest you which elements can be used there.
2. You can also use the elements and attributes view to select from a sidebar the element to add.
3. Once you have an element and you want to add an attribute, type the space separating the element name from the future attribute and Oxygen will pull up a list of attributes from which you can select. If an attribute is compulsory, it is bold.
4. Values for attributes are also suggested by Oxygen based on the schema.
5. To enter an element, you can either start typing it, or you can select a portion of text to tag and click CTRL+E which will open a small window where you can type the first letters of an element's name and select.
6. You might need to repeatedly enter the same element. You can do the repeat with CTRL+/

You will often have to enter the current date, for example, when you describe your work in <change>↗. To facilitate this you can use the Code Templates function in Oxygen. Set a Code Template for the XML Editor and assign it the current date value. Then, while editing to enter today's date open Document/Content Completion, start the assistant and enter the date.

There is a green light on top right corner of your document. If it is red, it means something is not valid. Click on the small red bar on the side of the document to go to that point and read the message. Often this is enough, if you don't understand where the problem is, ask.

Zotero

Please check the Zotero guidelines for working with the group bibliography.