4. Add via Git¶

4.1. Main Objectives¶

The main purpose of this recipe is:

Learn how to set up and use git to commit to the FAIR Cookbook Github repository.

4.2. Graphical Overview of the FAIRification Recipe Objectives¶

4.3. Prerequisites and Getting Set up¶

We rely on GitHub infrastructure for hosting the documents making up the cookbook. The reliance of git subversion system ensures robust data provenance tracking as well as traceability of authors contributions.

To make the most of the GitHub infrastructure, we strongly advise about following the git flow process, which we will detail now.

Clone the repo, enter the directory, and test that you are in the master branch by issuing the following command from the terminal:

git clone http://github.com/FAIRplus/the-fair-cookbook/
cd the-fair-cookbook
git branch 

should show:

master

then issue the following git command:

git checkout -b my_username-my_recipe_branch master
git branch

should show:

my_recipe

This means you are working on the dedicated copy of the master branch, any change made there will not affect the master files.

When you are done with your edits, use:

git add .
git commit -m 'some meaninful message, possibly indicated that would be closing an issue'

followed by:

git push origin my_recipe_branch

If you are done with all the edits, you are now ready to send a “Pull Request” to the main branch. In GitHub speak and jargon, a pull request always specifies a repository and a branch to merge into from a development branch on a repo (forked from a repo and simple cloned from the main branch as we are currently doing)

When sending a Pull Request also known as PR, you will have to specify a reviewer known as an assignee in the GitHub world. This optimally ensures that someone will review the contribution before merging it with the main main branch of the repository. You should NEVER merge into the master branch without a review (unless you are the master owner / editor-in-chief / benevolent dictator for life).

Upon this pull request`, the assignee will perform a review of the contribution. The contribution will either be merged in the master if all the quality control checks have passed or will be sent for correction to the submitter. the submitter will carry out the correction and send a new pull request for revision, following the same pattern of revision, submission acceptance merge.

Key ideas:

Each recipe should be developed in its own branch from the main github repository or from a branch in a forked version of the said repository. more information from the
commit often
remember to pull before committing in order to incorporate the latest changes from the master.

4.3.1. test, test and test again before pushing!¶

So you just wrote a new recipe and you’d like to see how it looks in the FAIRplus cookbook, what do you need to know ?

Make sure your new recipe is listed in the _data/toc.yml file where toc.yml is a YAML formatted file defining the Table of Content of the FAIR Cookbook.
Make sure you have python virtualenv running and where you have installed the jupyter-book python module. If you don’t know what I am talking about, do the following:
1. install pyenv
2. once done, run pyenv install , for instance

pyenv install 3.7.5

3. then you need to create the virtual environment by invoking:

pyenv virtualenv faircb375 3.7.5

4. to use the virtual environment, you'll have to call it using the following command:

pyenv activate faircb375

	if all goes well, your terminal prompt should give you the status, indicate you are running in a virtualenv:

(venv372) hodr-MacBook-Pro-3:docs bob$

5. Now install the python module **jupyter-book**. to do so, simply issue the following command:

pip install jupyter-book

	NOTE: you may have to update **pip** if the system complains, sending a message looking like this 

to update pip, issue `pip install pip --upgrade'

	**Huzza!** You are now reading te test if yuor recipe can be built in the jupyter-book. To just do this, you need to run the following command from the root of the github branch.

jupyter-book build docs --overwrite

where - `build` is one of the command available from jupyter-book package - `docs` is the name of the target book (it has to be that string) - `--overwrite` is an parameter to the `'builds'` The command telling it to ...well discard all previously generated files by writing over them...pretty self explanatory so far. if all goes well, you should have a green banner. If the process fails, your terminal will display a stack trace, indicating that there is an error in your markdown files or your toc.yml. if all is well, test locally by start a jekyll server. To do so, you'll have to do:

cd docs
make serve

Open a new tab in your favourite browser and point to the url http://127.0.0.1:4000/the-fair-cookbook/

4.4. Option 1: Writing the recipe in Markdown syntax¶

use the recipe template available from the issue tracker “create new recipe”
the template uses the [Markdown syntax], for which guidelines are available here
the recipe template provides key sections for consistently structuring information about the process you want to document.
briefly, you will need to fill in the following 5 sections:

licence information: you may use the default information which is provided or provide the terms of use of your liking.
goal and objective of the recipe you need to summarize the task using keywords, ideally expressing them in terms of process or capability. you should also annotate the terms with an ontology term, coming from resources such as. EDAM.action or `OBI.planned_process or OBI.data_transformation
declare and list the input information types (data files, data types) and the expected output data types. you should use the table provided to structure the information and annotate those input. & output to indicate the file formats.

For doing so, we strongly recommend performing a mark-up by linking to either a FAIRsharing record about standards and with and EDAM.datatype
provide an overall graphical representation of the flow of actions required to accomplish the objectives set considering the set of input data elements.

the representation may be done using the Markdown syntax defined by the mermaid project*

graphic representation currently encompass visual representation such as Gantt chart, Flow Chart, Flow Diagram and Sequence Diagram. These diagrammatic representations are particularly useful to indicate key decision processes, action to perform and data transformation path which may be considered in various contexts.
provide executable code in the form a notebook. the code could be organized according to the cookie cutter templates for data science, which enhances the replicability of the process.

you may also provide a machine actionable workflow and associated containers for execution in a safe environment or as microservice.
don’t forget to fill in the table of authors and contributors, by making sure you provide the orcid for each of contributors and the contribution by using the CredIT role
consider minting a DOI for the new recipe, so it is citable and versioned.

4.5. Option 2: Writing the recipe as a Google document¶

The main benefits are the collaborative editing feature capabilities this allows. The main drawbacks are the conversion losses that are bound to happen when using add-ons such as:

:zap: this add-ons may create security concerns and may not run on the FAIRplus Google Drive, meaning the conversion would have to happen outside that private drive.