Guidelines authors

assets/img/2025-03-20-revised-github-process/workflow.tex

@@ -0,0 +1,92 @@
+\documentclass[tikz,dvisvgm,border=10pt]{standalone}
+\usetikzlibrary{shapes.geometric,shapes.symbols,shapes.callouts,shapes.multipart,shapes.misc,arrows,positioning,fit,backgrounds,shadows}
+
+\begin{document}
+\begin{tikzpicture}[
+    % Define styles for nodes with enhanced colors
+    doc/.style={draw, minimum width=5cm, minimum height=2cm, align=center, fill=blue!20, text=blue!80!black, font=\bfseries, rounded corners=3mm, drop shadow},
+    container/.style={draw=blue!50!black, fill=blue!10, fill opacity=0.15, inner sep=10mm, rounded corners=8mm, thick, dashed},
+    package/.style={draw, fill=blue!5, fill opacity=0.7, inner sep=3mm, rounded corners, text=blue!60!black, thick},
+    process/.style={draw, minimum width=2cm, minimum height=1cm, align=center, fill=blue!10, text=blue!60!black, font=\small\sffamily, rounded corners=2mm},
+    cylnode/.style={draw, cylinder, shape border rotate=90, aspect=0.3, minimum height=1cm, minimum width=2cm, align=center, fill=cyan!30, text=cyan!60!black, font=\small\sffamily},
+    dashboard/.style={circle, draw, minimum size=1cm, fill=green!20, text=green!60!black, font=\small\sffamily\bfseries},
+    document/.style={draw, shape=tape, tape bend top=none, minimum width=2cm, minimum height=1cm, align=center, dashed, fill=purple!10, text=purple!70!black, font=\small\sffamily\itshape},
+    thick_arrow/.style={->, line width=1mm, draw=blue!70!black},
+    arrow/.style={->, >=stealth, draw=gray!70!black},
+    title/.style={font=\bfseries\sffamily, align=center, text width=4cm, text=blue!70!black},
+    label/.style={font=\small\sffamily\itshape, inner sep=2pt, text=purple!80!black},
+    filename/.style={font=\small\sffamily\itshape, text=orange!70!brown}
+]
+
+% Add a background for the entire diagram
+\begin{scope}[on background layer]
+    \fill[rounded corners=10mm, gray!5] (-2,-8) rectangle (16,4.5);
+\end{scope}
+
+% Create environment steps first
+\node[dashboard] (checkout) at (5,0) {Git};
+\node[process, below=0.8cm of checkout] (detect) {Detect\\Dependencies};
+\node[process, below=0.8cm of detect] (setup) {Setup Environment\\(Python/R)};
+\node[cylnode, below=0.8cm of setup] (cache) {Cache\\Environment};
+
+% Environment connections
+\draw[arrow] (checkout) -- (detect);
+\draw[arrow] (detect) -- (setup);
+\draw[arrow] (setup) -- (cache);
+
+% Custom environment script - with label higher
+\node[document] (customenv) at ([xshift=-3cm]setup.west) {setup-env-ci.sh};
+\draw[arrow, draw=purple!50!black] (customenv) -- (setup) node[pos=0.35, above=12pt, label] {Customize};
+
+% Environment setup container with title above
+\node[title] at (checkout.north) [above=5mm] {Environment Setup \\\textcolor{orange!70!brown}{(global-env.yml)}};
+
+% Use layers to put containers in the background - adjusted fit
+\begin{scope}[on background layer]
+    \node[package, fill=blue!5] (env) [fit=(checkout) (detect) (setup) (cache) (customenv)] {};
+\end{scope}
+
+% Create render steps first - explicitly aligned with env.east anchor
+\path (env.east) ++(3cm,0) coordinate (render_start);
+\node[process, fill=blue!20] (restore) at ([yshift=3cm]render_start) {Restore\\Environment};
+\node[process] (quarto) at ([yshift=-0.8cm]restore.south) {Setup Quarto};
+\node[process] (compile) at ([yshift=-0.8cm]quarto.south) {Render\\Documents};
+\node[process] (artifact) at ([yshift=-0.8cm]compile.south) {Upload as\\Artifact};
+\node[process, fill=green!30, text=green!60!black, font=\small\sffamily\bfseries] (deploy) at ([yshift=-0.8cm]artifact.south) {Deploy to\\GitHub Pages};
+
+% Render connections
+\draw[arrow] (restore) -- (quarto);
+\draw[arrow] (quarto) -- (compile);
+\draw[arrow] (compile) -- (artifact);
+\draw[arrow] (artifact) -- (deploy);
+
+% Custom render script - with label higher and inverted direction
+\node[document] (customrender) at ([xshift=2.5cm]compile.east) {setup-render-ci.sh};
+\draw[arrow, draw=purple!50!black] (customrender) -- (compile) node[pos=0.35, above=12pt, label] {Customize};
+
+% Render and deploy container with title above
+\node[title] at (restore.north) [above=5mm] {Render \& Deploy \\\textcolor{orange!70!brown}{(publish-render.yml)}};
+
+% Use layers to put containers in the background - adjusted fit
+\begin{scope}[on background layer]
+    \node[package, fill=blue!10] (render) [fit=(restore) (quarto) (compile) (artifact) (deploy) (customrender)] {};
+\end{scope}
+
+% Main flow connections
+\draw[thick_arrow] (env.east) -- (render.west |- env.east);
+
+% Finally create the main workflow container around everything
+\begin{scope}[on background layer]
+    % Create invisible nodes to capture the title areas
+    \node[opacity=0] (env_title_anchor) at ([yshift=10mm]checkout.north) {};
+    \node[opacity=0] (render_title_anchor) at ([yshift=10mm]restore.north) {};
+
+    % Make container fit these invisible nodes too, ensuring it goes high enough
+    \node[container, fit=(env_title_anchor) (render_title_anchor) (env) (render)] (workflow_container) {};
+
+    % Place the title well above the container with colored filename
+    \node[font=\bfseries\Large, text=blue!70!black, align=center] at ([yshift=10mm]workflow_container.north) {Main Workflow \\\textcolor{orange!70!brown}{(build.yml)}};
+\end{scope}
+
+\end{tikzpicture}
+\end{document}

site/_handle_dependencies_R.qmd

@@ -0,0 +1,60 @@
+For the R community, Computo relies on the [**renv**](https://rstudio.github.io/renv/articles/renv.html) package manager to setup a reproducible environment that handles `R` dependencies. Setting up **renv** for use within your repository requires the following steps. First, you need to initialize your repository to work with **renv**. This is done by running:
+
+```r
+# Initialize your repo to work with renv
+renv::init()
+```
+
+The purpose of this function is to create a `renv.lock` file that registers the version of R and quarto along with all the packages and their versions that **renv** finds in your notebook.
+
+Upon cloning one of our template however, the `renv.lock` file already exists. Therefore, when you execute `renv::init()`, you will be provided with the following choices:
+
+```r
+> renv::init()
+This project already has a lockfile. What would you like to do? 
+
+1: Restore the project from the lockfile.
+2: Discard the lockfile and re-initialize the project.
+3: Activate the project without snapshotting or installing any packages.
+4: Abort project initialization.
+```
+
+You should choose **Option 2**, which will extend the message box with:
+
+```r
+- Linking packages into the project library ... Done!
+- Lockfile written to "~/Projects/computo/my-computo-submission/renv.lock".
+- renv activated -- please restart the R session.
+```
+
+prompting you to restart your R session which you should do right away. If you now inspect the existing `renv.lock` file, you will see the R version you locally run on along with a bunch of packages listed there. This is because `template-computo-R.qmd` includes the **ggplot2** package by default to showcase how you can include plots in your paper. As a result, **renv** registers **ggplot2** along with all its dependencies in the `renv.lock` file.
+
+Now you can write your contribution, using all the packages you need. Install the required dependencies as usual (via `install.packages()` or via the RStudio IDE) or using **renv** built-in `install()` function:
+
+```r
+# Install packages you need
+renv::install("ggplot2") # or equivalently install.packages("ggplot2")
+```
+
+Non-CRAN packages (*e.g.* Github packages) can be used. To install such packages, you need to first install the **remotes** package. Then, if you want to install the development version of *e.g.* the **gt** package hosted by `rstudio` GitHub account (useful for nicely and easily formatting tables btw), you would do:
+
+```r
+install.packages("remotes")
+remotes::install_github("rstudio/gt")
+```
+
+Once you are done, you need to freeze the environment and package versions that are going to be used to run the calculations within your paper. This is achieved via:
+
+```r
+# Register environment and package versions
+renv::snapshot()
+```
+
+::: {.callout-warning title="The `renv.lock` file"}
+The `renv.lock` should be versioned with git. Other files that `renv::snapshot()` might produce should be listed under `.gitignore` and therefore not put under versioning.
+:::
+
+More details for using **renv** can be found:
+
+- either on the [**renv**](https://rstudio.github.io/renv/articles/renv.html) package website,
+- or on the Quarto website at this [dedicated page](https://quarto.org/docs/projects/virtual-environments.html#using-renv).

site/_handle_dependencies_julia.qmd

@@ -0,0 +1 @@
+More to come.

site/_handle_dependencies_python.qmd

@@ -0,0 +1,54 @@
+If you are writing a contribution that relies on Python code and Python packages, you can locally install and use those packages any way you like.
+
+We then handle your Python package dependencies in our CI/CD scripts using [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html), which requires that you ship a file called `environment.yml` that lists your dependencies. This file should be stored at the root of your repository. Here is the typical content of such a file:
+
+```yml
+name: computo
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11
+  - jupyter
+  - matplotlib
+  - pandas
+  - scipy
+  - seaborn
+  - scikit-learn
+  - numpy=1.24
+  - numba
+```
+
+The `name:` entry
+
+: You can choose a name of your liking. It should be short with no spaces and uniquely refer to the title or content of your contribution.
+
+The `channels:` entry
+
+: In most cases, you should leave it to the value `conda-forge`. Some advanced configurations for which you might want to reference other channels can be found by browsing our list of published papers [here](https://github.com/computorg?q=published&type=all&language=&sort=).
+
+The `dependencies:` entry
+
+: This is where you should list all your dependencies. It is good practice to list `python` itself so you can provide the version you used as done above. Other dependencies written in the outer list will be installed from the listed channel using micromamba. It is recommended to indicate which version was used as done above for **numpy** for instance. If your work relies on packages that have not been made available as conda packages, you can add a `pip` entry to the outer list and add those packages under the `pip:` list as in:
+
+```yml
+name: clayton
+channels:
+  - conda-forge
+dependencies:
+  - jupyter
+  - numpy
+  - scipy
+  - matplotlib
+  - pandas
+  - seaborn
+  - pip:
+    - clayton
+```
+
+::: {.callout-note title="Automatic registration of packages"}
+Currently and differently from what we provide for R users, we do not have implemented an automatic way of registering environment, packages and their versions. Hence, you are expected to do that manually.
+:::
+
+::: {.callout-tip title="`requirements.txt`"}
+If your work exclusively depends on packages installed from `pip` and you are used to listing dependencies in a `requirements.txt` file, you can ship this file instead of the `environment.yml` file and our CI/CD scripts should run smoothly.
+:::