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 4 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
286 changes: 172 additions & 114 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,155 +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:

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think issues are quite a good way to raise suggestions - on slack they get lost. So I would be more encouraging in this section - search for duplicates, otherwise go for it.


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.).

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

browser?


## 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.
---

### Cloning the Repository
## 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:

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.
- You authored 100% of the content you are contributing.

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Not sure what that means. Often people will contribute text that's collaboratively authored - or just a publicly available resources. I would just keep this focused on the license, and then maybe fact-checking.

- You have the necessary rights to that content.
- The content may be provided under the project's license.

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Specify the default - CC BY unless otherwise specified?

@richarddushime richarddushime May 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

better

@richarddushime richarddushime May 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

shifting this to Readme


### Development - Dev Containers and 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.
## Local Development Setup

#### Prerequisites
Choose the setup method that suits your workflow.

- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
### Standard Setup (Git + Hugo)

**Prerequisites**

- [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.

**Steps**

1. Clone the repository:

```bash
git clone https://github.com/forrtproject/forrtproject.github.io.git
cd forrtproject.github.io
```

2. Start the development server:

```bash
hugo server -D
```

The `-D` flag includes draft pages. Open `http://localhost:1313` in your browser to preview the site.

---

### 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/)
- 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**

1. Open `.devcontainer/devcontainer.json` in VSCode.

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is this still up to date? The tech stack has changed a fair bit and I have never touched the file.

@richarddushime richarddushime May 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

i doubt if there is even people who use it
so to keep the docs simplified i will remove it and leave the standard informations for 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

#### Steps
For R users who prefer to work entirely within RStudio.

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`.
**Prerequisites**

### Development - R-Studio
- [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/)

#### Prerequisites
**Steps**

* [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/)
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.

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

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.


#### Steps
> **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.

If you are a R user and would prefer to work in RStudio, you need to:
---

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.
## Contribution Workflow

To edit it locally, you will then need to:
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 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.
1. **Fork and clone** — fork the repository to your account and clone it locally (if you haven't already).

Please note that RStudio is not designed for website development, so you may find it easier to use the Dev Containers method described above.
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.

@LukasWallrich LukasWallrich May 23, 2026

Copy link
Copy Markdown
Contributor

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.

@richarddushime richarddushime May 24, 2026

Copy link
Copy Markdown
Contributor Author

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