The NMRLipids project is currently divided into four subprojects (NMRLipids I-IV) which are shortly described in the About page.

Workflow in the past
The NMRLipids I project (and partly the NMRLipids II) was made such that the preliminary version of the manuscript was published in arXiv, and then this manuscript was discussed and further contributions were submitted in the blog posts and comments. After some time the new contributions were collected and a new version of the manuscript was written and the final version was submitted to a peer revieved journal.

Current workflow
While doing the NMRLipids I project we were effectively collecting information into the blog, and then moving it into the new version of the manuscript. However, I believe that it would be more efficient to collect the information directly into the manuscript. Thus, in the current workflow the manuscript is constantly updated while new contributions are done. This is already applied in the NMRLipids II project, and will be applied in the NMRLipids III and IV.

Shortly, the manuscript found from the Manucript folder in GitHub repository for each project will be kept updated according to the contributions and comments in the blog and GitHub repositories. This manuscript will then evolve to the version which will be submitted to a peer reviewed journal. Practical details are below.

Practical implementation of the workflow
The NMRLipids GitHub organization contains (or will contain) separate repository for each project. The repositories should always have these subfolders containing pre-defined information (based on suggestion by Hubert Santuz):

Manuscript -- contains the current version of the manuscript in raw LaTex format and in pdf.
Data -- contains the data used in the manuscript
Figs -- contains the figures and scripts to generate those from the Data folder.
Scratch -- contains everything else and all the work in progress which is not ready for the Data folder.

In addition there may be some other folders, and while we gather more experience on this approach we can update the structure if needed.

The up-to-date manuscript for each project will be always found from the Manuscript folder. The manuscript also contains a ToDo list with specific issues to be improved (unless it is finished). The discussion will be done in GitHub issue tracker and in this blog.  The goal is that there will be references in the manuscript to the relevant ongoing discussions (if someone has idea how to automatically synchronize this, please let us know).

The contributions to the projects can done by taking part into these ongoing discussions in the blog or in GitHub. You can also directly add and modify files in GitHub repositories (data, figures, manuscript or any other file) and make a pull request to include changes in the master branch. You should not be too shy on doing this since the Git version control saves the history and changes are easy to track. It might take a while to get familiar with Git and GitHub but it is worth of it. There are lot of instructions available by googling.

The original guidelines about the authorship of the manuscripts still apply to this blog and the GitHub.

How to follow and get overview of the project status?
The current version of the manuscript should be found from the Manuscript folder of the project's GitHub repository (NMRLipids I, NMRLipids II, NMRLipids III and IV coming soon). The manuscript should contain a ToDo list and other links to the discussions on the open topics. Thus by reading the manuscript one should get quite good overview about the status. More detailed discussion should be found from the GitHub issues and from this blog (as mentioned above, the idea is to link these in the manuscript, let's hope that this works).

If you have any questions or comments about the workflow, contributing or following of the projects, do not hesitate to comment this page.

No comments:

Post a Comment

Please sign in before writing your comment.