4. Add via Git¶
4.1. Main Objectives¶
The main purpose of this recipe is:
Learn how to set up git to commit to the FAIR Cookbook
4.2. Graphical Overview of the FAIRification Recipe Objectives¶
4.3. Prequisites 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
then issue the following git command:
git checkout -b my_username-my_recipe_branch master git branch
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'
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
master 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 master as we are currently doing)
When sending a
Pull Request aslo 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
master branch of the repository.
You should NEVER merge into the master branch without a review (unless you are the master owner / editor in chielf / benevolent dictator for life).
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.
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
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.ymlfile 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:
once done, run
pyenv install <python version>, 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 jupier-book package - `docs` is the name of the target book (it has to be that string) - `--overwrite` is an parameter to the `'buils'` The command telling it to ...well discard all previously generated files by writing over them...pretty seff explanatory so far. if all goes well, you should have a green banner. If the process fails, your terminal will display a stack trace, indicateing 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
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:
goal and objective of the recipe you need to summerize the task using keywords, ideally expressing them in terms of
capability. you should also annotate the terms with an ontology term, coming from resources such as.
declare and list the input information types (data files, data types) and the expected output datatypes. you should use the table provided to structure the information and annotate those input. & output to indicate the file formats.
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 representatiion such as Gantt chart, Flow Chart, Flow Diagram and Sequence Diagram. These diagrammtic represntations are particularly useful to indicate key decision processes, action to perform and data transfrormation 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 citeable and versionned.
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 googledrive, meaning the conversion would have to happen outside that private drive.
This page is released under the Creative Commons 4.0 BY license.