Skip to content

Update Contributing Documentation #727

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
richarddushime wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Update Contributing Documentation #727

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7f7acf3
update readme and contributing instructions
richarddushime Mar 31, 2026
5cbed0c
Merge branch 'main' into contr
richarddushime May 21, 2026
a31aac1
Contributing Guide
richarddushime May 21, 2026
dd9b0a2
Forrt info
richarddushime May 21, 2026
163588b
fix:reqs changes
richarddushime May 24, 2026
291258e
Not to date script and unusable currently
richarddushime May 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 0 additions & 48 deletions .devcontainer/dev/devcontainer.json
View file
Open in desktop

This file was deleted.

258 changes: 143 additions & 115 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Copy Markdown
Contributor

@LukasWallrich LukasWallrich May 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would highly recommend usethis here for PR management - it's the most accessible way to do that.

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.
Copy link
Copy Markdown
Contributor

@LukasWallrich LukasWallrich May 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to say something about AI here? I would say contributions co-authored with agents are welcome, but only if you have reviewed both code and content fully. Also, if a contribution consists of running a single prompt, consider posting the prompt/idea as an issue instead - it will then often be faster for us to run the prompt with the full understanding of the coding conventions than to review and integrate purely vibe-coded contributions.

Copy link
Copy Markdown
Contributor Author

@richarddushime richarddushime May 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think no need to add it, we still dont have a large number of contributors

Loading
Loading