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

Merged
LukasWallrich merged 10 commits into from
Jun 10, 2026
+193 −247
Merged

Update Contributing Documentation #727

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 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
651c2a5
Address review: restore CC BY-NC-SA site license, rework issues/AI/li…
LukasWallrich Jun 10, 2026
cb94603
Update contribution guidelines for issue submissions
LukasWallrich Jun 10, 2026
2fcdd9d
Update CONTRIBUTING.md
LukasWallrich Jun 10, 2026
05b0f61
Merge branch 'main' into contr
LukasWallrich Jun 10, 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.

272 changes: 155 additions & 117 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,155 +2,193 @@

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)
- [Questions, Ideas & Suggestions](#questions-ideas--suggestions)
- [Local Development Setup](#local-development-setup)
- [Standard Setup](#standard-setup-git--hugo)
- [RStudio Setup](#rstudio-setup)
- [Contribution Workflow](#contribution-workflow)
- [Contributing with AI tools](#contributing-with-ai-tools)
- [Content, Licensing & Fact-Checking](#content-licensing--fact-checking)
- [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.
## Questions, Ideas & Suggestions

If you then still feel the need to ask a question and need clarification, we recommend the following:
Issues are the best place to raise a question, suggest an improvement, or propose a resource for ilusion (unless you can find the more specific submission form).

- 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.
- Have a quick look through the existing [Issues](https://github.com/forrtproject/forrtproject.github.io/issues) in case the same idea is already being discussed.
- Otherwise, [open a new Issue](https://github.com/forrtproject/forrtproject.github.io/issues/new) and go for it — a question, a rough idea, or a fully worked-out proposal are all welcome. Share whatever context is helpful.

We will take care of the issue as soon as possible. Right now we run on volunteer time, so please be patient!
FORRT is maintained by volunteers, so response times may vary. We appreciate your patience and your contribution.

## I Want To Contribute
---

> ### 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 Development Setup

### Cloning the Repository
Choose the setup method that suits your workflow.

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.
### Standard Setup (Git + Hugo)

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

### Development - Dev Containers and VSCode
- [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.

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

#### Prerequisites
1. Fork and Clone the repository:

- [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/)
```bash
git clone https://github.com/forrtproject/forrtproject.github.io.git
cd forrtproject.github.io
```

#### Steps
2. Start the development server:

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`.
```bash
hugo server -D
```

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

#### Prerequisites
---

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

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

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

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

To edit it locally, you will then need to:
**Steps**

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. 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.
Comment thread
LukasWallrich marked this conversation as resolved.
3. Use `usethis` to manage your Pull Request workflow from within R — it is the most accessible approach for R users:

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

### Contributing with AI tools

Contributions co-authored with AI agents are welcome, but only if you have **fully reviewed both the code and the content** yourself and can stand behind them.

If a contribution amounts to running a single prompt, please consider posting the prompt or idea as an [issue](https://github.com/forrtproject/forrtproject.github.io/issues) instead. It is often faster for us to run it ourselves, with full knowledge of the project's coding conventions, than to review and integrate unverified, vibe-coded output.

### Content, Licensing & Fact-Checking

- Please **fact-check** anything you add and cite sources where relevant, so the site stays accurate and trustworthy.
- Make sure you have the right to share the content under the licence applicable to the relevant section of the site.
- Unless you tell us otherwise, contributions are assumed to be offered under [**CC BY 4.0**](https://creativecommons.org/licenses/by/4.0/).

---

## 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.
Comment thread
LukasWallrich marked this conversation as resolved.
Loading
Loading