From 7f7acf3a1044489c27ea326274fd58c9470f2cad Mon Sep 17 00:00:00 2001 From: richarddushime Date: Tue, 31 Mar 2026 11:47:00 +0200 Subject: [PATCH 1/5] update readme and contributing instructions --- CONTRIBUTING.md | 54 ++++++++++++++++++++++++++++++++----------------- README.md | 15 +++++++++----- 2 files changed, 46 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a9894e32e0f..87926025a36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,11 +33,41 @@ We will take care of the issue as soon as possible. Right now we run on voluntee > ### Legal Notice > When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. -### Cloning the Repository +# Local setup (quick start) -For FORRT contributors, you can clone this repository to your local machine and make changes on the feature branch. For now, we do not use a separate development branch. Proposed changes must be made in a feature branch. Please then create a pull request into the master branch. +**Fork and clone** + - Fork the repository to your own GitHub account (or use the Dev Container / RStudio workflows below). -For external contributors, this website operates on the [fork and pull](https://reflectoring.io/github-fork-and-pull/) model, so you will need to fork this repository to your GitHub account of choice and then clone it to your local machine. +To run the FORRT website locally, you need to install. + +- [Git](https://git-scm.com/downloads) +- [Hugo](https://gohugo.io/getting-started/installing/) +- [Visual Studio Code](https://code.visualstudio.com/) *(Optional: you can use your preferred text editor.)* + +Clone the repository: + + ```bash + git clone https://github.com/forrtproject/forrtproject.github.io.git + cd forrtproject.github.io + ``` +Start the development server: + + ```bash + hugo server -D + ``` +Open `http://localhost:1313` in your browser to preview changes. + +Then +1. **Create a branch** + - Create a descriptive feature branch (for example, `fix-typo-contributing` or `add-new-resource-page`). +2. **Make and test your changes** + - Apply your edits, run the site locally (preview changes), and ensure there are no errors. +3. **Commit with a clear message** + - Commit your changes with a concise, meaningful message describing what you changed and why. +4. **Push and open a Pull Request** + - Push your branch to your fork and open a Pull Request against the `master` branch of `forrtproject/forrtproject.github.io`, linking any relevant issues and briefly summarizing your changes. + +For more information about Git commands, see the official documentation [here](https://docs.github.com/en/get-started/using-git/about-git). ### Development - Dev Containers and VSCode @@ -45,7 +75,7 @@ A way to run the project locally without installing Hugo on the host machine is #### Prerequisites -- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +- [Git](https://git-scm.com/downloads) - [Docker](https://docs.docker.com/get-docker/) - For Windows, make sure to install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) - [Visual Studio Code](https://code.visualstudio.com/) @@ -62,7 +92,7 @@ A way to run the project locally without installing Hugo on the host machine is #### Prerequisites -* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +* [Git](https://git-scm.com/downloads) * [Hugo](https://gohugo.io/getting-started/installing/) * [R](https://cran.r-project.org/) * [RStudio](https://www.rstudio.com/products/rstudio/download/) @@ -78,20 +108,8 @@ If you are a R user and would prefer to work in RStudio, you need to: * Create project as a subdirectory of: `click Browse and decide where you want put it` 2. Before editing, try to run it locally using the blogdown Addins in RStudio. -To edit it locally, you will then need to: - -1. Fork this GitHub repo (create a version of the FORRT repo on your own account). -2. Clone this repo you just added in your own account: `git clone https://github.com/yourusername/forrtproject.github.io.git` in a terminal window. -3. To run the website locally, make sure you are still in `FORRT/` dir and type `hugo server -D` in your terminal. - - The -D option is to serve the website including draft .md files. -4. Create a new branch with your name or the feature you would like to add (e.g. outreach). Depending on your code editor, the way to do this will vary (e.g. in Visual Studio Code you can click on "master" in the bottom left and select "new branch"). -5. Make changes on your branch. Check that it the website is working using again `hugo server -D`. -6. Select what changes you want to add now and "stage" them with Git. -7. Commit your changes and add a message that describes the changes. -8. Then you can push this branch to GitHub. -9. Create a pull request to the original FORRT repo. -Please note that RStudio is not designed for website development, so you may find it easier to use the Dev Containers method described above. +Please note that RStudio is not designed for website development, so you may find it easier to use other methods above. ## Deployment & Staging diff --git a/README.md b/README.md index d5137e66357..3aab1e5748f 100644 --- a/README.md +++ b/README.md @@ -45,14 +45,19 @@ If you think you can help in any of the areas listed above (and we bet you can) There, we can direct you towards relevant documents and tasks. -- But if you are interested in contributing to the **FORRT manuscript**, a google doc version can be found here: https://tinyurl.com/FORRTworkingDOC. -- If you are interested in contributing to the **Website**, see specific instructions below, and please check out FORRTโ€™s Github [to-do](https://github.com/forrtproject/forrt/projects/1) and [open issues](https://github.com/forrtproject/forrt). - Please note that it's very important to us that we maintain a positive and supportive environment for everyone who wants to participate. When you join us we ask that you follow our code of conduct in all interactions both on and offline. -#### FORRT Website on Github +- If you are interested in contributing to the **FORRT manuscript**, you can find a Google Doc version [here](https://tinyurl.com/FORRTworkingDOC). + +#### Contributing + +This is the website for the **Framework for Open and Reproducible Research Training (FORRT)**, built with [hugo](https://gohugo.io/), and deployed with [GitHub Actions](https://docs.github.com/en/actions). You can find the website at [forrt.org](https://forrt.org/). +- If you are interested in contributing to the **website**, see specific instructions below, and please check out FORRTโ€™s GitHub repository [open issues](https://github.com/forrtproject/forrtproject.github.io/issues). + +> [!IMPORTANT] +> There are many FORRT tools and initiatives you can contribute to. Check them out [here](https://github.com/forrtproject). -This is the website for the **Framework for Open and Reproducible Research Training (FORRT)**, built with [hugo](https://gohugo.io/), and deployed with [Github Actions](https://docs.github.com/en/actions). You can find the website at [forrt.org](https://forrt.org/). See CONTRIBUTING.md for more information on how to contribute. +See [Contributing](CONTRIBUTING.md) for more information on how to contribute. ## License From a31aac1b2c2a2c90bcb745c19ce7c38d8453dccb Mon Sep 17 00:00:00 2001 From: richarddushime Date: Thu, 21 May 2026 23:35:46 +0200 Subject: [PATCH 2/5] Contributing Guide --- CONTRIBUTING.md | 283 ++++++++++++++++++++++++++---------------------- 1 file changed, 156 insertions(+), 127 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3271ca2de0a..a8bd8c91a6f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,184 +2,213 @@ First off, thanks for taking the time to contribute! โค๏ธ -All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. ๐ŸŽ‰ +All types of contributions are encouraged and valued. Please read the relevant section before contributing โ€” it makes things smoother for everyone. The community looks forward to your contributions. ๐ŸŽ‰ -> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: -> -> - Star the repository -> - Share FORRT on your social media -> - Reference FORRT in your project's readme -> - Mention FORRT at local meetups and tell your friends/colleagues +> **Not ready to contribute code?** That's fine. You can still support FORRT by: +> - Starring the repository +> - Sharing FORRT on social media +> - Referencing FORRT in your project's readme +> - Mentioning FORRT at local meetups and to colleagues ## Table of Contents - [I Have a Question](#i-have-a-question) -- [I Want To Contribute](#i-want-to-contribute) +- [Legal Notice](#legal-notice) +- [Local Development Setup](#local-development-setup) + - [Standard Setup (Git + Hugo)](#standard-setup-git--hugo) + - [Dev Containers (VSCode)](#dev-containers-vscode) + - [RStudio Setup](#rstudio-setup) +- [Contribution Workflow](#contribution-workflow) +- [Deployment & Staging](#deployment--staging) + - [Production](#production) + - [Staging](#staging) + - [How Staging Works](#how-staging-works) + - [Monthly Reports](#monthly-reports) + +--- ## I Have a Question -Before you ask a question, it is best to search for existing [Issues](/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. +Before opening an issue, please: -If you then still feel the need to ask a question and need clarification, we recommend the following: +1. Search existing [Issues](/issues) โ€” your question may already be answered. +2. Join the FORRT Community on Slack [here](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) and Ask. -- Open an [Issue](/issues/new). -- Provide as much context as you can about the problem you're having. -- Provide project and platform versions (Hugo, Operating System etc.), depending on what seems relevant. +If you still need help: -We will take care of the issue as soon as possible. Right now we run on volunteer time, so please be patient! +- Open a [new Issue](/issues/new). +- Provide as much context as you can about the problem. +- Include relevant versions (Hugo, OS, etc.). -## I Want To Contribute +We run on volunteer time, so please be patient โ€” we'll get back to you as soon as we can. -> ### Legal Notice -> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. +--- -# Local setup (quick start) +## Legal Notice -For FORRT contributors, you can clone this repository to your local machine and make changes on the feature branch. For now, we do not use a separate development branch. Proposed changes must be made in a feature branch. Please then create a pull request into the main branch. +When contributing to this project, you confirm that: -To run the FORRT website locally, you need to install. +- You authored 100% of the content you are contributing. +- You have the necessary rights to that content. +- The content may be provided under the project's license. + +--- + +## Local Development Setup + +Choose the setup method that suits your workflow. + +### Standard Setup (Git + Hugo) + +**Prerequisites** - [Git](https://git-scm.com/downloads) - [Hugo](https://gohugo.io/getting-started/installing/) -- [Visual Studio Code](https://code.visualstudio.com/) *(Optional: you can use your preferred text editor.)* +- A text editor of your choice โ€” [Visual Studio Code](https://code.visualstudio.com/) is recommended. + +**Steps** -Clone the repository: +1. Clone the repository: ```bash git clone https://github.com/forrtproject/forrtproject.github.io.git cd forrtproject.github.io ``` -Start the development server: + +2. Start the development server: ```bash hugo server -D ``` -Open `http://localhost:1313` in your browser to preview changes. -Then -1. **Create a branch** - - Create a descriptive feature branch (for example, `fix-typo-contributing` or `add-new-resource-page`). -2. **Make and test your changes** - - Apply your edits, run the site locally (preview changes), and ensure there are no errors. -3. **Commit with a clear message** - - Commit your changes with a concise, meaningful message describing what you changed and why. -4. **Push and open a Pull Request** - - Push your branch to your fork and open a Pull Request against the `master` branch of `forrtproject/forrtproject.github.io`, linking any relevant issues and briefly summarizing your changes. + The `-D` flag includes draft pages. Open `http://localhost:1313` in your browser to preview the site. -For more information about Git commands, see the official documentation [here](https://docs.github.com/en/get-started/using-git/about-git). +--- -### Development - Dev Containers and VSCode +### Dev Containers (VSCode) -A way to run the project locally without installing Hugo on the host machine is via the use of Dev Containers. These are disposable development environments that run in containers, which ensure all dependences are installed as required and that host dependencies do not impact the project (or vice versa). This ensures reproducibility and consistency across different hosts, but does require a container runtime (Dockerd, containerd etc.) to be installed on the host machine. +Run the project locally without installing Hugo on your host machine. Dev Containers use Docker to provide a consistent, reproducible environment. -#### Prerequisites +**Prerequisites** - [Git](https://git-scm.com/downloads) - [Docker](https://docs.docker.com/get-docker/) - - For Windows, make sure to install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) -- [Visual Studio Code](https://code.visualstudio.com/) + - Windows users: also install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) +- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension -#### Steps +**Steps** -1. Open VSCode and ensure you have the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed in Visual Studio Code. -2. Open `.devcontainer/devcontainer.json` in VSCode. If you are on a Windows host, go to `.devcontainer\dev\devcontainer.json` and uncomment the line `"remoteUser": "root"` before continuing. -3. In the context menu of VSCode (Crl + Shift + P), select `Dev Containers: Open Folder in Container`. Alternatively, a pop-up will appear in the bottom right corner of the window asking if you want to open the folder in a container. Click on `Reopen in Container`. -4. Wait for the container to build. The context of VS Code will change. In the bottom left corner, you will see a green icon with the name of the container (Hugo Dev). -5. Run `hugo server -D`. The container will forward port 1313 to the host machine, so you can access the website at `http://localhost:1313`. +1. Open `.devcontainer/devcontainer.json` in VSCode. + - **Windows only:** open `.devcontainer\dev\devcontainer.json` and uncomment the line `"remoteUser": "root"` before continuing. +2. Open the Command Palette (`Ctrl+Shift+P`) and select **Dev Containers: Open Folder in Container**. Alternatively, click **Reopen in Container** in the pop-up that appears in the bottom-right corner. +3. Wait for the container to build. The bottom-left corner will show a green **Hugo Dev** badge when ready. +4. Start the server: -### Development - R-Studio + ```bash + hugo server -D + ``` -#### Prerequisites + The container forwards port 1313 to your host โ€” open `http://localhost:1313` to preview the site. -* [Git](https://git-scm.com/downloads) -* [Hugo](https://gohugo.io/getting-started/installing/) -* [R](https://cran.r-project.org/) -* [RStudio](https://www.rstudio.com/products/rstudio/download/) -* [blogdown](https://bookdown.org/yihui/blogdown/) +--- -#### Steps +### RStudio Setup -If you are a R user and would prefer to work in RStudio, you need to: +For R users who prefer to work entirely within RStudio. -1. Open R Studio, then go in the Menu > New Project... > Version Control > Git - * Repository URL: `git clone https://github.com/forrtproject/forrtproject.github.io.git` - * Project directory name: `FORRT` - * Create project as a subdirectory of: `click Browse and decide where you want put it` -2. Before editing, try to run it locally using the blogdown Addins in RStudio. +**Prerequisites** -To edit it locally, you will then need to: +- [Git](https://git-scm.com/downloads) +- [Hugo](https://gohugo.io/getting-started/installing/) +- [R](https://cran.r-project.org/) +- [RStudio](https://www.rstudio.com/products/rstudio/download/) +- [blogdown](https://bookdown.org/yihui/blogdown/) + +**Steps** + +1. In RStudio, go to **File โ†’ New Project โ†’ Version Control โ†’ Git**. + - Repository URL: `https://github.com/forrtproject/forrtproject.github.io.git` + - Project directory name: `FORRT` + - Choose a location with **Browse**. +2. Run the site locally using the **blogdown Addins** in RStudio, or run `hugo server -D` in the RStudio terminal. + +> **Note:** RStudio is not designed for website development. For a smoother experience, consider the [Standard Setup](#standard-setup-git--hugo) or [Dev Containers](#dev-containers-vscode) instead. + +--- -1. Fork this GitHub repo (create a version of the FORRT repo on your own account). -2. Clone this repo you just added in your own account: `git clone https://github.com/yourusername/forrtproject.github.io.git` in a terminal window. -3. To run the website locally, make sure you are still in `FORRT/` dir and type `hugo server -D` in your terminal. - - The -D option is to serve the website including draft .md files. -4. Create a new branch with your name or the feature you would like to add (e.g. outreach). Depending on your code editor, the way to do this will vary (e.g. in Visual Studio Code you can click on "main" in the bottom left and select "new branch"). -5. Make changes on your branch. Check that it the website is working using again `hugo server -D`. -6. Select what changes you want to add now and "stage" them with Git. -7. Commit your changes and add a message that describes the changes. -8. Then you can push this branch to GitHub. -9. Create a pull request to the original FORRT repo. +## Contribution Workflow -Please note that RStudio is not designed for website development, so you may find it easier to use other methods above. +All proposed changes must be made on a feature branch and submitted via a Pull Request to `main`. We do not use a separate development branch. + +1. **Fork and clone** โ€” fork the repository to your account and clone it locally (if you haven't already). + +2. **Create a feature branch** โ€” use a short, descriptive name: + + ```bash + git checkout -b fix-typo-contributing + # or + git checkout -b add-new-resource-page + ``` + +3. **Make and test your changes** โ€” run `hugo server -D` to preview the site locally and verify no errors appear. + +4. **Commit with a clear message** โ€” describe what you changed and why: + + ```bash + git commit -m "Fix broken link in contributing guide" + ``` + +5. **Push and open a Pull Request** โ€” push your branch and open a PR targeting the `main` branch of `forrtproject/forrtproject.github.io`. Link any related issues and briefly summarise your changes. + +For more on Git, see the [official documentation](https://docs.github.com/en/get-started/using-git/about-git). + +--- ## Deployment & Staging -The FORRT website uses a dual deployment strategy to ensure quality and enable collaborative testing: - -### Production Deployment - -- **URL**: [https://forrt.org](https://forrt.org) -- **Workflow**: `.github/workflows/deploy.yaml` -- **Trigger**: Pushes to `main` branch -- **Target**: GitHub Pages (`gh-pages` branch) -- **Purpose**: Serves the live, production website - -### Staging Deployment - -- **URL**: [https://staging.forrt.org](https://staging.forrt.org) -- **Workflow**: `.github/workflows/staging-aggregate.yaml` -- **Trigger**: Pull requests to `main`, monthly schedule (1st of each month), or manual dispatch -- **Target**: External repository (`forrtproject/webpage-staging`) -- **Purpose**: Preview combined changes from all open PRs - -#### How Staging Works - -The staging deployment uses an **aggregation strategy** to provide a unified preview environment: - -1. **Automatic Aggregation**: When any PR is opened, synchronized, or reopened, the workflow: - - Collects all open, non-draft PRs targeting `main` - - Creates a temporary aggregation branch from `main` - - Attempts to merge each PR in sequence - -2. **Conflict Handling**: - - PRs that merge cleanly are included in the staging build - - PRs with merge conflicts are skipped but logged - - The deployment continues with all compatible PRs - -3. **Deployment Comments**: Each PR receives an automated comment indicating: - - โœ… Successfully deployed (for PRs without conflicts) - - โš ๏ธ Skipped due to conflicts (for conflicting PRs) - - Deployment timestamp and staging URL - -4. **Queuing & Timeouts**: - - Workflow uses concurrency control to queue builds (not cancel) - - Job timeouts (10-20 minutes) prevent indefinite blocking - - Draft PRs are filtered out to avoid unnecessary builds - -5. **Branch Cleanup**: - - Keeps only the 5 most recent staging branches - - Automatically cleans up older staging-aggregate branches - -#### Viewing Staging Changes - -- Visit [https://staging.forrt.org](https://staging.forrt.org) to see the combined state of all open, compatible PRs -- Note: Staging shows aggregated changes from **all** open PRs, not individual PR changes -- PRs with merge conflicts won't appear in staging until conflicts are resolved - -#### Monthly Reports - -On the 1st of each month, an automated deployment report is created as a GitHub issue with: +The FORRT website uses a dual deployment strategy to ensure quality and enable collaborative review. + +### Production + +| Detail | Value | +|---|---| +| URL | [https://forrt.org](https://forrt.org) | +| Workflow | `.github/workflows/deploy.yaml` | +| Trigger | Push to `main` | +| Target | GitHub Pages (`gh-pages` branch) | + +### Staging + +| Detail | Value | +|---|---| +| URL | [https://staging.forrt.org](https://staging.forrt.org) | +| Workflow | `.github/workflows/staging-aggregate.yaml` | +| Trigger | PR opened/updated against `main`; 1st of each month; manual dispatch | +| Target | External repository (`forrtproject/webpage-staging`) | +| Purpose | Preview the combined state of all open, compatible PRs | + +> Staging shows **aggregated** changes from all open PRs โ€” not individual PR previews. Visit [https://staging.forrt.org](https://staging.forrt.org) to see the combined state. PRs with merge conflicts will not appear until those conflicts are resolved. + +### How Staging Works + +When a PR is opened, synchronised, or reopened, the staging workflow: + +1. **Aggregates open PRs** โ€” collects all non-draft PRs targeting `main` and merges them in sequence onto a temporary branch. +2. **Handles conflicts gracefully** โ€” PRs that merge cleanly are included; conflicting PRs are skipped and logged. +3. **Posts a deployment comment** on each PR: + - โœ… Successfully included in staging + - โš ๏ธ Skipped due to merge conflicts +4. **Manages concurrency** โ€” builds are queued (not cancelled) with job timeouts of 10โ€“20 minutes. +5. **Cleans up old branches** โ€” keeps only the 5 most recent staging branches. + +### Monthly Reports + +On the 1st of each month, an automated GitHub issue is created with: + - Total PRs processed - Successfully merged PRs -- Skipped PRs (with conflict information) +- Skipped PRs (with conflict details) - Deployment statistics + +--- +Thank you for contributing to FORRT and helping build a more open, reproducible, and inclusive research culture. From dd9b0a25e00654be7f6da7c8faceb91171a41714 Mon Sep 17 00:00:00 2001 From: richarddushime Date: Fri, 22 May 2026 00:01:59 +0200 Subject: [PATCH 3/5] Forrt info --- README.md | 81 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 48 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 7caff9028dd..865fc00f7d9 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,79 @@ -# FORRT +# FORRT โ€” Framework for Open and Reproducible Research Training [![Hugo CICD](https://github.com/forrtproject/forrtproject.github.io/actions/workflows/deploy.yaml/badge.svg?branch=main)](https://github.com/forrtproject/forrtproject.github.io/actions/workflows/deploy.yaml) [![pages-build-deployment](https://github.com/forrtproject/forrtproject.github.io/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/forrtproject/forrtproject.github.io/actions/workflows/pages/pages-build-deployment) [![Website](https://img.shields.io/website?down_color=red&down_message=offline&label=forrt.org&up_color=blue&up_message=online&url=https%3A%2F%2Fforrt.org%2F)](https://forrt.org) -This is repository for the website of **FORRT - the Framework for Open and Reproducible Research Training**. +Source repository for **[forrt.org](https://forrt.org)** โ€” a didactic and pedagogical infrastructure for open and reproducible research training in higher education. -## Welcome! +--- -First and foremost, Welcome! ๐ŸŽ‰ Willkommen! ๐ŸŽŠ Bienvenue! +## Welcome -This document is a hub to give you some information about the FORRT project. The term โ€˜onboardingโ€™ refers to the process of integrating new arrivals into the organization and its culture - where one can acquire the necessary knowledge, skills, and behaviors in order to become an effective organizational member. +First and foremost, welcome! ๐ŸŽ‰ Willkommen! ๐ŸŽŠ Bienvenue! -### The problem +This document provides an overview of the FORRT project and the ways in which you may contribute to its mission. -* Recently, the scientific community took steps to reflect a widespread awareness of, and call for, improved practices ushering in the โ€œcredibility revolutionโ€ including higher standards of evidence, preregistration, direct replication, transparency, and openness. -Structurally, three pillars were proposed to carry social sciences towards academic utopia: opening scientific communication, restructuring incentives and practices, and collaborative and crowdsourced science. -* However, ongoing attempts have neglected an essential aspect of the academic machinery: students. And indeed, current norms for the teaching and mentoring in higher-education are rooted in obsolete practices of bygone eras. +--- -### The solution +## About FORRT -* In our view, a scientific utopia has a fourth pillar, whose principal goal is to familiarize students, who are future consumers of science and perhaps themselves knowledge producers, with the intricacies of the process of science. -* We believe the teaching and mentoring of reproducible and open research practices is the clearest indicator of the degree to which institutions and/or departments embody principles of credible science. -* This demonstration goes beyond paying lip service to best practices, and ensures that students are trained to engage in these practices wheresoever. +### The Problem -**FORRT** - *a framework for open and reproducible research training* - aims to provide a didactic and pedagogical infrastructure designed to recognize and support the teaching and mentoring of open and reproducible research in tandem with prototypical subject matters in higher education. +The scientific community has recently undertaken substantial efforts to address longstanding concerns about the reliability and transparency of research, ushering in what has been termed a "credibility revolution." These efforts have encompassed higher standards of evidence, preregistration, direct replication, greater transparency, and open dissemination of data and materials. Structurally, three pillars have been proposed to advance the social sciences toward greater epistemic rigour: opening scientific communication, restructuring incentives and practices, and fostering collaborative and crowdsourced science. -### What do we need? +Yet ongoing attempts at reform have largely neglected a foundational element of the academic enterprise: the training of students. Current norms for teaching and mentoring in higher education remain rooted in practices that predate โ€” and are often incompatible with โ€” the standards now demanded of contemporary scholarship. -**You!** (In whatever way you can help). +### The Solution -We need expertise in website construction, fundraising, proofing, user experience design, transferring knowledge across platforms, experts in pedagogy/didactics in higher education, database maintenance (for cataloguing and classifying resources), documentation, technical writing and project management. +FORRT proposes a fourth pillar of scientific reform, whose principal aim is to familiarise students โ€” the future consumers of scientific knowledge and prospective knowledge producers โ€” with the rigorous, transparent, and reproducible practices that characterise credible research. We believe that the systematic teaching and mentoring of reproducible and open research practices constitutes the most meaningful indicator of the degree to which institutions and departments genuinely embody the principles of credible science, going well beyond mere rhetorical commitment to best practices. -We'd love your feedback along the way. -Our primary goal is to support teachers and mentors trying to bridge the gap between modern and current norms in higher education. And hopefully, making this rather new OS revolution sustainable by promoting the adoption of Open and Reproducible tenets to the teaching and mentoring of prototypical subject matters in higher education. +> **FORRT** aims to provide a didactic and pedagogical infrastructure designed to recognise and support the teaching and mentoring of open and reproducible research in tandem with prototypical subject matters in higher education. -And while FORRT is aimed at concerned teachers and mentors, we're excited to plug another hole in the leaky pipeline by supporting the professional development of any and all of our contributors. If you're looking to learn to code, try out working collaboratively, get some experience writing grant applications or translate your skills to the digital domain, we're here to help. +--- -### Get involved +## Get Involved -If you think you can help in any of the areas listed above (and we bet you can) or in any of the many areas that we haven't yet thought of (and here we're sure you can!) then please check out our [contributors' guidelines](https://docs.google.com/document/d/1Yd1LrAd96MCfr01wIubEGz4iO92_Qr_OY2qWrle3Vro/edit?usp=sharing) and [join FORRTโ€™s Slack](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) with a message at FORRT telling how you think you can help: +FORRT is sustained by the contributions of scholars, educators, students, and practitioners across disciplines and career stages. We welcome expertise and effort in: website development, research and content writing, user experience design, pedagogy and didactics in higher education, database curation and maintenance, documentation, translation, science communication, fundraising, and project management. -> โ€œHi everyone, I'm a ___ (i.e., professional status: grad student, postdoc, AP) in ____ (i.e., field of study) at ____(i.e., institution) and would be happy to help out with _____. Feel free to contact me.โ€ - -There, we can direct you towards relevant documents and tasks. +We are also committed to supporting the professional development of contributors at all levels. Whether you are seeking experience in collaborative software development, academic writing, grant applications, or the translation of disciplinary expertise to the digital domain, FORRT is a community in which such growth is actively encouraged. -Please note that it's very important to us that we maintain a positive and supportive environment for everyone who wants to participate. When you join us we ask that you follow our code of conduct in all interactions both on and offline. +Please note that participation in FORRT requires adherence to our code of conduct in all interactions. -- If you are interested in contributing to the **FORRT manuscript**, you can find a Google Doc version [here](https://tinyurl.com/FORRTworkingDOC). +### Join the Community -#### Contributing +- **Slack**: [Join FORRT's Slack workspace](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) and introduce yourself with a brief message: -This is the website for the **Framework for Open and Reproducible Research Training (FORRT)**, built with [hugo](https://gohugo.io/), and deployed with [GitHub Actions](https://docs.github.com/en/actions). You can find the website at [forrt.org](https://forrt.org/). -- If you are interested in contributing to the **website**, see specific instructions below, and please check out FORRTโ€™s GitHub repository [open issues](https://github.com/forrtproject/forrtproject.github.io/issues). + > "Hi everyone, I am a ___ (e.g., doctoral researcher, postdoctoral fellow, assistant professor) in ___ (field of study) at ___ (institution), and I would be glad to contribute to ___." + + A community member will direct you to relevant documents and open tasks. + +- **Manuscript**: Contribute to the FORRT manuscript via [this collaborative Google Doc](https://tinyurl.com/FORRTworkingDOC). +- **Other initiatives**: Explore the full range of FORRT tools and projects at [github.com/forrtproject](https://github.com/forrtproject). + +--- + +## Contributing to the Website + +This site is built with [Hugo](https://gohugo.io/) and deployed via [GitHub Actions](https://docs.github.com/en/actions). Contributions are submitted as Pull Requests targeting the `main` branch. > [!IMPORTANT] -> There are many FORRT tools and initiatives you can contribute to. Check them out [here](https://github.com/forrtproject). +> See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup instructions, contribution workflow, and deployment details. -See [Contributing](CONTRIBUTING.md) for more information on how to contribute. +**Quick start:** + +```bash +git clone https://github.com/forrtproject/forrtproject.github.io.git +cd forrtproject.github.io +hugo server -D +``` + +Open `http://localhost:1313` in your browser to preview the site locally. Open issues are tracked at [github.com/forrtproject/forrtproject.github.io/issues](https://github.com/forrtproject/forrtproject.github.io/issues). + +--- ## License -Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. +Creative Commons License + +This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/). From 163588b3dc1d253d6a49f3d1071b881e0bc71b17 Mon Sep 17 00:00:00 2001 From: richarddushime Date: Sun, 24 May 2026 10:35:12 +0200 Subject: [PATCH 4/5] fix:reqs changes --- .devcontainer/dev/devcontainer.json | 48 -------------------- CONTRIBUTING.md | 70 +++++++++-------------------- README.md | 31 ++++--------- update_academic.sh | 2 + 4 files changed, 31 insertions(+), 120 deletions(-) delete mode 100644 .devcontainer/dev/devcontainer.json diff --git a/.devcontainer/dev/devcontainer.json b/.devcontainer/dev/devcontainer.json deleted file mode 100644 index 5775eecc513..00000000000 --- a/.devcontainer/dev/devcontainer.json +++ /dev/null @@ -1,48 +0,0 @@ -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu -{ - "name": "Hugo Dev", - "image": "mcr.microsoft.com/devcontainers/base:noble", - "features": { - "ghcr.io/devcontainers/features/hugo:1": { - "extended": true, - "version": "0.158.0" - }, - "ghcr.io/devcontainers/features/node:1": { - "nodeGypDependencies": true, - "version": "lts", - "nvmVersion": "latest" - }, - "ghcr.io/devcontainers-contrib/features/k6:1": { - "version": "latest" - } - }, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // Hugo listens on 1313 by default when building a draft with `hugo server -D` - "forwardPorts": [ - 1313 - ], - - // Use 'postAttachCommand' to run commands after the container is attached (so after remote.containers.copyGitConfig has run) - // (Optional) After attaching to the container, unset the gpg.ssh.program setting to 1Password compatibility. - "postAttachCommand": "git config --global --unset gpg.ssh.program", - - // Configure tool-specific properties. - "customizations": { - "settings": { - "remote.containers.copyGitConfig": true - }, - "vscode": { - "extensions": [ - "aaron-bond.better-comments", - "github.vscode-github-actions", - "redhat.vscode-yaml" - ] - } - }, - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // (Optional) Based on this https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user Windows hosts require root to run `hugo server -D`. - // "remoteUser": "root" -} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8bd8c91a6f..d2ee614bb2e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ First off, thanks for taking the time to contribute! โค๏ธ All types of contributions are encouraged and valued. Please read the relevant section before contributing โ€” it makes things smoother for everyone. The community looks forward to your contributions. ๐ŸŽ‰ -> **Not ready to contribute code?** That's fine. You can still support FORRT by: +You can support FORRT by: > - Starring the repository > - Sharing FORRT on social media > - Referencing FORRT in your project's readme @@ -13,10 +13,8 @@ All types of contributions are encouraged and valued. Please read the relevant s ## Table of Contents - [I Have a Question](#i-have-a-question) -- [Legal Notice](#legal-notice) - [Local Development Setup](#local-development-setup) - - [Standard Setup (Git + Hugo)](#standard-setup-git--hugo) - - [Dev Containers (VSCode)](#dev-containers-vscode) + - [Standard Setup](#standard-setup-git--hugo) - [RStudio Setup](#rstudio-setup) - [Contribution Workflow](#contribution-workflow) - [Deployment & Staging](#deployment--staging) @@ -31,26 +29,14 @@ All types of contributions are encouraged and valued. Please read the relevant s Before opening an issue, please: -1. Search existing [Issues](/issues) โ€” your question may already be answered. -2. Join the FORRT Community on Slack [here](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) and Ask. +- Take a moment to search existing [Issues](https://github.com/forrtproject/forrtproject.github.io/issues) โ€” your question or suggestion may already have been addressed. -If you still need help: +If you still need assistance: -- Open a [new Issue](/issues/new). -- Provide as much context as you can about the problem. -- Include relevant versions (Hugo, OS, etc.). +- Open a [new Issue](https://github.com/forrtproject/forrtproject.github.io/issues). +- Share as much relevant context as possible about the problem, question, or suggestion. -We run on volunteer time, so please be patient โ€” we'll get back to you as soon as we can. - ---- - -## Legal Notice - -When contributing to this project, you confirm that: - -- You authored 100% of the content you are contributing. -- You have the necessary rights to that content. -- The content may be provided under the project's license. +FORRT is maintained by volunteers, so response times may vary. We appreciate your patience and contribution. --- @@ -68,7 +54,7 @@ Choose the setup method that suits your workflow. **Steps** -1. Clone the repository: +1. Fork and Clone the repository: ```bash git clone https://github.com/forrtproject/forrtproject.github.io.git @@ -85,33 +71,6 @@ Choose the setup method that suits your workflow. --- -### Dev Containers (VSCode) - -Run the project locally without installing Hugo on your host machine. Dev Containers use Docker to provide a consistent, reproducible environment. - -**Prerequisites** - -- [Git](https://git-scm.com/downloads) -- [Docker](https://docs.docker.com/get-docker/) - - Windows users: also install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) -- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension - -**Steps** - -1. Open `.devcontainer/devcontainer.json` in VSCode. - - **Windows only:** open `.devcontainer\dev\devcontainer.json` and uncomment the line `"remoteUser": "root"` before continuing. -2. Open the Command Palette (`Ctrl+Shift+P`) and select **Dev Containers: Open Folder in Container**. Alternatively, click **Reopen in Container** in the pop-up that appears in the bottom-right corner. -3. Wait for the container to build. The bottom-left corner will show a green **Hugo Dev** badge when ready. -4. Start the server: - - ```bash - hugo server -D - ``` - - The container forwards port 1313 to your host โ€” open `http://localhost:1313` to preview the site. - ---- - ### RStudio Setup For R users who prefer to work entirely within RStudio. @@ -123,6 +82,7 @@ For R users who prefer to work entirely within RStudio. - [R](https://cran.r-project.org/) - [RStudio](https://www.rstudio.com/products/rstudio/download/) - [blogdown](https://bookdown.org/yihui/blogdown/) +- [usethis](https://usethis.r-lib.org/) โ€” recommended for PR management **Steps** @@ -131,8 +91,17 @@ For R users who prefer to work entirely within RStudio. - Project directory name: `FORRT` - Choose a location with **Browse**. 2. Run the site locally using the **blogdown Addins** in RStudio, or run `hugo server -D` in the RStudio terminal. +3. Use `usethis` to manage your Pull Request workflow from within R โ€” it is the most accessible approach for R users: + + ```r + usethis::pr_init("my-feature-branch") # create a branch + usethis::pr_push() # push and open a PR on GitHub + usethis::pr_finish() # clean up after the PR is merged + ``` + + See the [usethis documentation](https://usethis.r-lib.org/index.html) for the full workflow. -> **Note:** RStudio is not designed for website development. For a smoother experience, consider the [Standard Setup](#standard-setup-git--hugo) or [Dev Containers](#dev-containers-vscode) instead. +> **Note:** RStudio is not designed for website development. For a smoother experience, consider the [Standard Setup](#standard-setup-git--hugo) instead. --- @@ -211,4 +180,5 @@ On the 1st of each month, an automated GitHub issue is created with: - Deployment statistics --- + Thank you for contributing to FORRT and helping build a more open, reproducible, and inclusive research culture. diff --git a/README.md b/README.md index 865fc00f7d9..378a08a5eed 100644 --- a/README.md +++ b/README.md @@ -18,17 +18,7 @@ This document provides an overview of the FORRT project and the ways in which yo ## About FORRT -### The Problem - -The scientific community has recently undertaken substantial efforts to address longstanding concerns about the reliability and transparency of research, ushering in what has been termed a "credibility revolution." These efforts have encompassed higher standards of evidence, preregistration, direct replication, greater transparency, and open dissemination of data and materials. Structurally, three pillars have been proposed to advance the social sciences toward greater epistemic rigour: opening scientific communication, restructuring incentives and practices, and fostering collaborative and crowdsourced science. - -Yet ongoing attempts at reform have largely neglected a foundational element of the academic enterprise: the training of students. Current norms for teaching and mentoring in higher education remain rooted in practices that predate โ€” and are often incompatible with โ€” the standards now demanded of contemporary scholarship. - -### The Solution - -FORRT proposes a fourth pillar of scientific reform, whose principal aim is to familiarise students โ€” the future consumers of scientific knowledge and prospective knowledge producers โ€” with the rigorous, transparent, and reproducible practices that characterise credible research. We believe that the systematic teaching and mentoring of reproducible and open research practices constitutes the most meaningful indicator of the degree to which institutions and departments genuinely embody the principles of credible science, going well beyond mere rhetorical commitment to best practices. - -> **FORRT** aims to provide a didactic and pedagogical infrastructure designed to recognise and support the teaching and mentoring of open and reproducible research in tandem with prototypical subject matters in higher education. +For a deeper look into FORRTโ€™s mission, initiatives, and available resources, visit **[forrt.org](https://forrt.org)**. --- @@ -42,14 +32,9 @@ Please note that participation in FORRT requires adherence to our code of conduc ### Join the Community -- **Slack**: [Join FORRT's Slack workspace](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) and introduce yourself with a brief message: - - > "Hi everyone, I am a ___ (e.g., doctoral researcher, postdoctoral fellow, assistant professor) in ___ (field of study) at ___ (institution), and I would be glad to contribute to ___." +- **Slack**: [Join FORRT's Slack workspace](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) and introduce yourself. - A community member will direct you to relevant documents and open tasks. - -- **Manuscript**: Contribute to the FORRT manuscript via [this collaborative Google Doc](https://tinyurl.com/FORRTworkingDOC). -- **Other initiatives**: Explore the full range of FORRT tools and projects at [github.com/forrtproject](https://github.com/forrtproject). +- **Other initiatives**: Explore the full range of FORRT tools and projects at [forrt.org](https://forrt.org/). --- @@ -58,7 +43,7 @@ Please note that participation in FORRT requires adherence to our code of conduc This site is built with [Hugo](https://gohugo.io/) and deployed via [GitHub Actions](https://docs.github.com/en/actions). Contributions are submitted as Pull Requests targeting the `main` branch. > [!IMPORTANT] -> See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup instructions, contribution workflow, and deployment details. +> See [CONTRIBUTING](CONTRIBUTING.md) for full setup instructions, contribution workflow, and deployment details. **Quick start:** @@ -68,12 +53,14 @@ cd forrtproject.github.io hugo server -D ``` -Open `http://localhost:1313` in your browser to preview the site locally. Open issues are tracked at [github.com/forrtproject/forrtproject.github.io/issues](https://github.com/forrtproject/forrtproject.github.io/issues). +Open [http://localhost:1313](http://localhost:1313) in your browser to preview the site locally. + +You can find open issues [ here](https://github.com/forrtproject/forrtproject.github.io/issues). and contribute to any that interest you. --- ## License -Creative Commons License +Creative Commons License -This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/). +This work is licensed under a [Creative Commons Attribution 4.0 International](http://creativecommons.org/licenses/by/4.0/). diff --git a/update_academic.sh b/update_academic.sh index 5167224f34c..897aa8d33db 100755 --- a/update_academic.sh +++ b/update_academic.sh @@ -1,3 +1,5 @@ +# Not updated + #!/usr/bin/env bash # Source Themes Academic: Theme updater From 291258eeeff3eb156397619b8856ef185ec8684d Mon Sep 17 00:00:00 2001 From: richarddushime Date: Sun, 24 May 2026 10:53:18 +0200 Subject: [PATCH 5/5] Not to date script and unusable currently --- update_academic.sh | 53 ---------------------------------------------- 1 file changed, 53 deletions(-) delete mode 100755 update_academic.sh diff --git a/update_academic.sh b/update_academic.sh deleted file mode 100755 index 897aa8d33db..00000000000 --- a/update_academic.sh +++ /dev/null @@ -1,53 +0,0 @@ -# Not updated - -#!/usr/bin/env bash - -# Source Themes Academic: Theme updater -# Checks for available updates and then asks to install any updates. -# https://sourcethemes.com/academic/ -# -# Command: bash ./update_academic.sh - -# Check for prerequisites. -if [ ! -d .git ]; then - echo "ERROR: This tool is for Git repositories only." - exit 1; -fi - -function view_update () { - echo -e "Checking for updates...\n" - cd themes/academic - git fetch - git log --pretty=oneline --abbrev-commit --decorate HEAD..origin/master - cd ../../ -} - -# Function to update Academic -function do_update () { - # Apply any updates - git submodule update --remote --merge - - # - Update Netlify.toml with required Hugo version - if [ -f ./netlify.toml ]; then - # Postfix '.0' to Hugo min_version as sadly it doesn't map to a precise semantic version. - version=$(sed -n 's/^min_version = //p' themes/academic/theme.toml | tr -d '"') - version="${version}.0" - echo "Set Netlify Hugo version to v${version}" - sed -i.bak -e "s/HUGO_VERSION = .*/HUGO_VERSION = \"$version\"/g" ./netlify.toml && rm -f ./netlify.toml.bak - fi - - echo - echo "View the release notes at: https://sourcethemes.com/academic/updates" - echo "If there are breaking changes, the config and/or front matter of content" \ - "may need upgrading by following the steps in the release notes." -} - -# Display currently installed version (although could be between versions if updated to master rather than tag) -version=$(sed -n 's/^version = "//p' themes/academic/data/academic.toml) -echo -e "Source Themes Academic v$version\n" - -# Display available updates -view_update - -# Apply any updates -do_update