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 0ee5f5eddf2..d2ee614bb2e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,155 +2,183 @@ 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 +You can 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) +- [Local Development Setup](#local-development-setup) + - [Standard Setup](#standard-setup-git--hugo) + - [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: +- Take a moment to search existing [Issues](https://github.com/forrtproject/forrtproject.github.io/issues) — your question or suggestion may already have been addressed. -- 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 assistance: -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](https://github.com/forrtproject/forrtproject.github.io/issues). +- Share as much relevant context as possible about the problem, question, or suggestion. -## I Want To Contribute +FORRT is maintained by volunteers, so response times may vary. We appreciate your patience and contribution. -> ### 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 Development Setup -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. +Choose the setup method that suits your workflow. -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. +### Standard Setup (Git + Hugo) -### Development - Dev Containers and VSCode +**Prerequisites** -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. +- [Git](https://git-scm.com/downloads) +- [Hugo](https://gohugo.io/getting-started/installing/) +- A text editor of your choice — [Visual Studio Code](https://code.visualstudio.com/) is recommended. -#### Prerequisites +**Steps** -- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -- [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/) +1. Fork and Clone the repository: -#### Steps + ```bash + git clone https://github.com/forrtproject/forrtproject.github.io.git + cd forrtproject.github.io + ``` -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`. +2. Start the development server: -### Development - R-Studio + ```bash + hugo server -D + ``` -#### Prerequisites + The `-D` flag includes draft pages. Open `http://localhost:1313` in your browser to preview the site. -* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -* [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/) +- [usethis](https://usethis.r-lib.org/) — recommended for PR management -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. +**Steps** -Please note that RStudio is not designed for website development, so you may find it easier to use the Dev Containers method described above. +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. +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) instead. + +--- + +## Contribution Workflow + +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. diff --git a/README.md b/README.md index 89f730c73eb..378a08a5eed 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,66 @@ -# 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. +For a deeper look into FORRT’s mission, initiatives, and available resources, visit **[forrt.org](https://forrt.org)**. -**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. +--- -### What do we need? +## Get Involved -**You!** (In whatever way 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. -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. +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. -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. +Please note that participation in FORRT requires adherence to our code of conduct in all interactions. -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. +### Join the Community -### Get involved +- **Slack**: [Join FORRT's Slack workspace](https://join.slack.com/t/forrt/shared_invite/zt-alobr3z7-NOR0mTBfD1vKXn9qlOKqaQ) and introduce yourself. -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: +- **Other initiatives**: Explore the full range of FORRT tools and projects at [forrt.org](https://forrt.org/). -> “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. +--- -- 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). +## Contributing to the Website -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. +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. -#### FORRT Website on Github +> [!IMPORTANT] +> See [CONTRIBUTING](CONTRIBUTING.md) for full setup instructions, contribution workflow, and deployment details. -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. +**Quick start:** + +```bash +git clone https://github.com/forrtproject/forrtproject.github.io.git +cd forrtproject.github.io +hugo server -D +``` + +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
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 4.0 International](http://creativecommons.org/licenses/by/4.0/). diff --git a/update_academic.sh b/update_academic.sh deleted file mode 100755 index 5167224f34c..00000000000 --- a/update_academic.sh +++ /dev/null @@ -1,51 +0,0 @@ -#!/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