Get involved in the project!¶

Welcome! gofoss.net is a free and open source project, so anyone can review the website's code and add improvements. Join us today and learn about all the ways to get involved!

Improve content, add features, fix bugs
Enhance the user experience, design new artwork
Help with translations
Moderate discussions
Maintain the code

Contribution guidelines¶

Get in touch

No need to open an Issue on GitLab if you want to discuss or have a question. Simply reach out on social media:

Follow @gofoss_today on Twitter

Follow @don_atoms on Mastodon

Message @gofosstoday on Reddit

Message @gofoss on Lemmy

Join our chat on Matrix

Send us an email

Open an Issue

Instructions	Guidelines
Do some research	• Look for similar contributions before submitting your own • There's a good chance somebody else had the same issue or feature proposal • Get in contact with the gofoss.net community • Search the Issue Tracker • Check the Roadmap
File an Issue	• If nothing shows up during your research, you can file an Issue • Sign in to GitLab • Browse to the gofoss.net Issue Tracker • Click on the `New Issue` button • Fill in the title • Make sure to select the correct template: `content_request`: suggestions on new or improved content, e.g. new software, missing or incorrect information, spelling or grammar mistakes, readability improvement, etc. `feature_request`: suggestions on new website features, e.g. improved navigation, enhanced layout, new illustrations, dark mode, etc. `bug_report`: unexpected behavior of the website, e.g. broken links, issues loading on certain devices, etc.
Get involved in the review process	• All Issues are publicly discussed and reviewed • Make sure to follow the discussions related to your Issue • Answer any questions & review others' contributions • It's as valuable as contributing yourself • Set up email notifications to stay informed
Wait for the Issue to be resolved or closed	• We do our best to close Issues fast • In turn, we ask that you remain available for clarifying questions or corrections • Please note that if we don't hear back from you, we may close your Issue

Work on open Issues

Issue branching workflow¶

Branches	Guidelines
`main`	• The `main` branch is the production branch • Any commit to the `main` branch is automatically deployed from GitLab to Netlify • The `main` branch is therefore protected • It is only accessible to `maintainers` in the gofoss.net team
`dev`	• The `dev` branch is created off the `main` branch • This is where new content, features & patches are developed & tested • The `dev` branch is only accessible to `maintainers` in the gofoss.net team • The `dev` branch is merged into `main` when it is ready to be deployed into production
`issue`	• Each Issue should reside in its own branch • `issue` branches are created off the `dev` branch • When work on an Issue is complete, it gets merged back into `dev` • `issue` branches therefore never interact directly with `main` • Both gofoss.net `maintainers` & external contributors can work on `issue` branches

Forking workflow¶

Instructions	Guidelines
Pick an Issue to work on	• Check the Tracker for Issues marked as `accepting_merge_requests` • Those Issues are open for external contributions • Before you start working on an Issue, get in contact with the gofoss.net team • Either leave a comment in the Issue you want to work on • Or send us a message via Mastodon, Twitter or email • There is also a matrix channel where the gofoss.net devs hang out (invite only) • Wait until someone from the gofoss.net team validates your contribution request
Fork, clone & sync the gofoss.net repository	• Sign in to GitLab • Head over to the gofoss.net project • Click on the `Fork` button • This creates a copy of the gofoss.net project on your own GitLab repository • On your local machine, open a terminal & create a project folder: `mkdir ~/git_projects` • Clone your GitLab repository: `cd ~/git_projects` `git clone https://gitlab.com/<YOUR_USERNAME>/gofoss.git` • Move to the local copy of your repository: `cd ~/git_projects/gofoss` • Create a link with the upstream gofoss.net project to keep your fork in sync: `git remote add upstream https://gitlab.com/curlycrixus/gofoss.git` • Regularly sync with the `dev` branch of the upstream project: `cd ~/git_projects/gofoss` `git fetch upstream` `git checkout dev` `git pull upstream dev` `git push origin dev` • Else, if your fork is too outdated, your Merge Request might get rejected
Set up the development environment	• Define your accounts default identity: `git config user.email "<USER>@example.com"` `git config user.name "<USERNAME>"` • Install the lastest Python version & dependencies: `sudo apt install python3 python3-pip` • Make sure Python version 3 is installed: `python3 --version` • Install Mkdocs: `sudo apt install mkdocs` • Install Material for Mkdocs: `pip install mkdocs-material` • Install the multi-language plugin: `pip install mkdocs-static-i18n` • Install dependencies: `pip install -r requirements.txt`
Commit locally & push to remote	• Create a new `issue` branch, respecting the naming convention `[content/feature/bug]-[#issueID]-[short description]` • For example: `git checkout -b feature-#72-add-dark-mode` • Switch to the new branch: `git checkout feature-#72-add-dark-mode` • Start coding: add content & features or fix bugs • Preview local changes in your browser on `localhost:8000` with the command: `mkdocs serve` • If everything works as expected, add the code to the staging area: `git add .` • Commit the changes & make sure to add a clear comment: `git commit -m "<CLEAR COMMENT>"` • Finally, push the `issue` branch to your remote repository: `git push -u origin feature-#72-add-dark-mode`
Open a Merge Request	• Sign in to GitLab • Browse to `https://gitlab.com/<YOUR_USERNAME>/gofoss/-/merge_requests` • Click on the `New merge request` button • Select the source branch: `<USERNAME>/gofoss/feature-#72-add-dark-mode` • Select the target branch: `curlycrixus/gofoss/dev` • Click on the `Compare branches and continue` button • Make sure to select the `merge_request` template • Provide a clear title & description for your Merge Request • Select the option `Delete source branch when merge request is accepted` • Click on the button `Create merge request`
Get involved in the review process	• All Merge Requests are publicly discussed & reviewed • Make sure to follow the discussions related to your Merge Request • Answer any questions • Set up email notifications to stay informed
Wait for validation	• A gofoss.net `maintainer` will pull your `issue` branch into their local repository • They'll review & make sure it doesn't break anything • If the `maintainer` has comments, you need to update your Merge Request • If all is well, the `maintainer` will merge your changes into his local `dev` branch & push to the gofoss.net repository • Your contribution is now part of the gofoss.net project! • Other developers should pull from the gofoss.net repository to sync
Delete branch	• After your Merge Request has been merged, the `issue` branch `feature-#72-add-dark-mode` should have automatically been deleted • If this is not the case, delete it manually • You can now safely pull the changes from the upstream repository
Licensing	By contributing to gofoss.net, you agree that your contributions will be published under AGPLv3.

Directory structure¶

Please note that the overall directory structure must remain unchanged:

.
├─ .gitlab/             # issue & merge request templates
│
├─ docs/
│  │
│  ├─ assets/
│  │  └─ css/           # stylesheets (.css), local fonts (.ttf) & admonition icons (.svg)
│  │  └─ echarts/       # echart files (.html, .min.js)
│  │  └─ img/           # image files (.svg, .png, etc.)
│  │
│  └─ *.xyz.md          # multi-language markdown files (.en.md, .fr.md, .de.md, etc.)
│
├─ overrides/           # theme extensions (home_xyz.html, main.html, overrides.xyz.min.css)
│
├─ LICENSE              # mkdocs-material license
│
├─ netlify.toml         # build instructions for netlify deploy
│
├─ requirements.toml    # build dependencies
│
├─ runtime.txt          # python version for netlify deploy
│
└─ mkdocs.yml           # mkdocs configuration file

Help with translations

Instructions	Guidelines
Join a mailing list	If you are reasonably literate in one or more of the target languages and have basic knowledge of markdown syntax, join the appropriate mailing list: • EN ‣ FR translation team (Framasoft community) • EN ‣ DE translation team • EN ‣ ES translation team • EN ‣ PL translation team
Chat with other translators	There is also a matrix channel where translators can hang out, coordinate and provide support.
Get access to translation files	Translators receive a link to access the project files.
Work with Framapad	• All translations are managed using the collaborative online text editor Framapad • Individual contributions are identified by a color code • They appear on the screen in real time • Please make sure to read the README file, which provides additional guidelines
Use the glossary	Be sure to use the GLOSSARY file when you translate text.
Keep the original text	Insert the translation just after the original text, while keeping the original text as is.
Preserve the code	Make sure all markdown and HTML formatting elements are preserved.
Respect other contributors	• Please respect the work of other contributors • If you disagree with a translation, you are welcome to make your own suggestions • But without modifying or deleting existing translations
Do not abuse your powers	Do not abuse your powers. Translation work is based on trust.
Validation	Translations are published on the website once they are 100% complete and have been reviewed by the project team.

Follow the Code of Conduct

Instructions	Guidelines
Rule #1	Agree to collaborate with people from around the world, regardless of gender, age, nationality, ethnicity, appearance, education, social background or religion.
Rule #2	Keep the discussion friendly, respectful, constructive and on topic. There is zero tolerance for rudeness. No flame wars; no trolling; no insults; no sexualized language; no public or private harassment; no doxing; no personal, racist, political or religious attacks.
Rule #3	Respect choices of the project team. We try to read, review and respond to questions, issues and merge request as best as possible – but remember, our time is limited. We also welcome suggestions, recommendations and contributions – which doesn't imply that every decision must be group consensus.
Rule #4	Avoid private discussions on project related matters, if there's no good reason for it. Such discussions should remain public, on GitLab or via the project's official communication channels.
Rule #5	Submit any complaint to gofoss@protonmail.com. Infringements of rules #1 to #4 may lead to appropriate corrective action. This includes kind reminders, written warnings, removal, editing or rejection of any inappropriate contribution, including posts, comments, commits, code, issues or merge requests, and ultimately a ban from the project.

Want to donate?¶

Thanks for your interest!

Most "free" websites sell ads, their users data or pay-walled content. In contrast, gofoss.net is truly free (as in free beer): free to use, free source code, free of ads, free of tracking, free of sponsored content, free of affiliate links, free of paywalls.

gofoss.net is a volunteer-run, non-profit project. All operating costs, development and content are funded solely by user donations. If you want to donate, or buy us a coffee, please click on the button below :)

Consider also supporting other open source developers. Or helping digital rights groups and software foundations to advocate for better privacy laws, user rights and the freedom to innovate: