With our “PROPRE” Project Guide, get a publishing committee and a development team to collaborate on creating your automated reports using the “PROPRE” methodology. Follow our suggestions for organization, tools and R development practices, for a controlled and benevolent DevOps practice.
It is possible to collaborate around git in a team composed of developers and non developers. In this guide “Organisation d’un projet collaboratif de publication PROPRE”, we explain how.
Although the guide is only available in French, the concept of ‘PROPRE’ and the list of chapters as presented below may be of interest to other teams who wants to collaborate around a common development project.
What is a “PROPRE” collaborative project?
Table of Contents
A “PROPRE” collaborative project is a project that follows the “PROPRE Publications Process” and is led by a multi-disciplinary team.
Following DREAL Pays de la Loire’s response to a call for projects from the Commissariat Général au Développement Durable (CGDD) at the end of 2015 on the theme of strategic knowledge of territories, a data service center was formed in 2018.
The “DREAL datalab” must provide easy access to the raw, aggregated and analyzed data produced and disseminate them.
In order to promote the success of the projects, modern development methods and the use of free and open-source tools have been tested.
The production of data and the analysis of these data now require their presentation in a reproducible framework for at least three reasons: confidence in the information, its freshness and the saving of time in producing new information.
Thus, the need arose to define a PROcessus to set up collaborative Projects of REproducible and therefore disseminable Publications. The acronym “PROPRE” was born (PROPRE means CLEAN in French).
The implementation of this process could only be done in a single team.
A multi-disciplinary team of agents from different DREALs was formed to test the process against the needs and constraints of each on a common collaborative project.
Details of the genesis and concepts of the process can be found in the digital book: It’s “PROPRE”!, written in French too.
What is in this R development guide?
This book, written in French, is intended for the various people involved in an “PROPRE” development process. We will distinguish three categories of content:
- [01 – coordination] : How to set up such a project, what are the roles to be distributed, what are the necessary means and tools, … ?
- [02 – editing] : How to define your needs, how to present the content of the documents, how to collaborate with the development team, … ?
- [03 – development] : How to launch the project technically, which tools to use, which development method with R, which are the best practices, … ?
Project steps in chronological order
Setting up the project
- [coordinate] – Definition of the coordination roles of the teams and the schedule : “How to coordinate the project?”
- [coord] – Setting up the communication tools : “The working tools”
- [coord] – Definition of the format and storage of the data: “What questions to ask about data management?”
- [dev] – Setting up the development project in conjunction with git, RStudio and GitLab: “Setting up a development project with RStudio and GitLab”
The DevOps development cycle
Each request from the editorial board will be listed in one or more tickets.
Generally speaking, for a production with R, the validation concerns (1) the general appearance of the production (excluding relevant content), (2) the content (not formatted), and (3) the content integrated in the production medium.
In the context of a “PROPRE” publication, validation is about the content creation support tools.
The development product is always a R package, documented, tested and versioned.
The intended end product is a reproducible publication created from this package.
The implementation steps should have separated the publication into different chapters, independent if possible.
The publication will be built in several steps, repeated for each chapter.
- UI first: Creation and validation of the appearance of the future product (bookdown, without content) and the way it is built by the users (How the publication creation menu appears).
- Rmd then :
- [dev]: Creation of the thumbnails of the package. Rather dedicated to the documentation of the development, they present the direct use of the created functions. The compiled thumbnails will be presented on a web site for validation of the content and data processing by the editorial committee [Ed].
- [edition] : Creation of the content of the texts of the publication. Titles and paragraphs are validated in the editorial committee. In theory, there should be no discussion on the structure of the chapter at this stage.
- User documentation. This is an extension of the Rmd then part, which should explain to users of the product how to use it. This includes
- Integration of the content into the product. In this phase, there should be no more discussion about appearance, content or substance. The R codes are fixed. It is mainly a matter of checking that everything goes well in the final product.
The 1., 2. and 3. can be done independently, in parallel.
The 4. is done at the end. It can be the end of the validation of a particular chapter. But not of a paragraph.
The guides required for the good realization of the development cycles are the following:
- [dev] – Create project tickets in the Kanban and use them as the reference for development: “Create tickets and manage communication and progress with a Kanban”
- [edit] – See the progress of ticket resolution and respond to developer queries: Follow the processing of its requirements
- [dev] – Develop using git, GitLab and RStudio as collaboration tools: “Collaborate on a Git project with Gitlab and Rstudio”
- [dev] – Develop a documented and tested package with the ‘Rmd first’ method. This method is valid for the above development steps: “Develop a documented and tested package with the ‘Rmd first’ method”
- For English speakers, there are complementary guides around the “Rmd First” method: Rmd First: When development starts with documentation and {fusen}: Create a package from a simple rmarkdown file
- [dev] – Keep in mind the “Practices, tips and tricks of coding with R”
User tests and deliveries
At the end of a cycle, the content is fixed, the development of new functionalities is fixed.
We enter a validation phase.
The development and publishing teams test the proper functioning of the tools
- [dev] Test and deliver: “Release: Validation – Delivery by [ChfDev]”
Learn more about PROPRE
Slide shows presenting the “PROPRE” process:
- Details of the genesis and concepts of the process can be found in the digital book: It’s “PROPRE”!
- the presentation of the approach (Sept 2020)
- assessment of the 1st case study as of Nov 30, 2020
- presentation to the spyrales community
- Publications issued from {propre.rpls} published in 2020
