From 80d117ba01cd70e6bdcb15a8a31b8f0cb4d3180e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yannik=20R=C3=B6del?= Date: Mon, 1 May 2023 19:35:08 +0200 Subject: [PATCH] Update Readme, Add contributing guide --- CONTRIBUTING.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 97 +++++++++++--------------------------- 2 files changed, 150 insertions(+), 69 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..749cded --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,122 @@ +# Entwickler-Dokumentation + +## Struktur + +Das Projekt läuft mit dem Static-Site-Generator [Eleventy](https://www.11ty.dev/). +Anders als bei anderen Eleventy-Projekten liegt hier aber nicht nur einen Internetauftritt, sondern mehrere. +Alle teilen sich gemeinsames CSS, CGI-Skripte und noch ein paar andere Geschichten. +Sie unterscheiden sich nur durch die konkreten Inhalte. + +Du solltest nach dem Auschecken (oder in der Online-GUI) folgende Ordnerstruktur vorfinden: + +- **assets/** – Hilfsdateien für alle Auftritte. Dieser Ordner ist später unter `/assets` per HTTP verfügbar. Alles, was in diesem Ordner liegt, wird 1:1 kopiert. +- **cgi-bin/** – CGI-Skripte liegen hier. Diese sind zwar für alle Auftritte verfügbar, sind aber nicht überall genutzt. Diese Skripte werden auch nicht direkt von außen aufgerufen. Stattdessen schreibt der HTTP-Server relevante Anfragen um. +- **includes/** – Layout und Template-Dateien. Siehe dazu die [Eleventy-Dokumentation](https://www.11ty.dev/docs/config/#directory-for-includes). +- **nix/** – [Nix](https://nixos.org/)-spezifisches. Wahrscheinlich musst du hier nichts tun. +- **playground/** – Das ist die Spielwiese. Wenn du irgendetwas ausprobieren möchtest, was grob zum Projekt passt, aber sonst keinen Platz in der Ordnerstruktur hat, leg es hier ab. +- **sites/** – Hier bekommt jeder Internetauftritt einen eigenen Unterordner. + - **<name>/** + - **\_static/** – Statischer Inhalt, der nur für diesen Auftritt gedacht ist. Inhalte in diesem Ordner werden ohne Änderungen später live verfügbar sein. + - **assets/** – Hilfsdateien für diesen Auftritt. Diese sind später unter `/assets` per HTTP verfügbar. + - **\_data/** – [Globale Datendateien](https://www.11ty.dev/docs/data-global/) für Eleventy. Hier sind Metadaten zu dem Internetauftritt gespeichert. + - **\_images/** – Hier sind Bilder gespeichert, die vor der Liveschaltung nochmals angepasst werden. Dazu gehört Beispiel die automatisierte Konvertierung in verschiedene Formate. + - **httpd.conf** – Konfigurationsdatei für den HTTP-Server [lighttpd](https://redmine.lighttpd.net/projects/lighttpd/wiki#Documentation). Diese bestimmt die finale Auslieferung der Seite + - _Alles andere_ in diesem Ordner sind Inhalte für die eigentliche Homepage. +- **styles/** – [SCSS](https://sass-lang.com/)-Dateien. Alles, was hier nicht mit einem Unterstrich beginnt, ist später in `/assets/css` verfügbar. +- **.eleventy.js** – [Eleventy-Konfigurationsdatei](https://www.11ty.dev/docs/config/). Unsere Config ist so aufgesetzt, dass die entsprechend eingestellte Seite (siehe unten) geladen wird. +- **.eleventyignore** – Ignore-Datei für Eleventy. Diese enthält Pfade, die beim Bauen der Seite ignoriert werden. + +## Lokale Entwicklung + +Um das Projekt lokal zu bauen, musst du zunächst [Node](https://nodejs.org) sowie [git](https://git-scm.com/) installieren. +Dann kannst du das Repository klonen (stelle sicher, dass ein SSH Schlüssel in deinem Codeberg-Account [hinterlegt](https://docs.codeberg.org/security/ssh-key/) ist): + +```shell +git clone git@codeberg.org:angestoepselt/homepage.git +``` + +Dann führst du im Ordner des Projekts (`cd homepage`) folgenden Befehl aus: + +```shell +npm install +``` + +Das installiert sämtliche zur Entwicklung benötigten Abhängigkeiten. +Evtl. dauert das ein paar Minuten–hol dir ruhig einen Kaffee! +Du kannst `npm install` ruhig alle paar Wochen mal ausführen, um auf dem aktuellen Stand zu bleiben. + +Anschließend kompilierst du die CSS-Dateien, damit du später nicht nur eine weiße Textwand zu sehen bekommst: + +```shell +npm run build:styles +``` + +Wenn du allerdings explizit an den CSS-Dateien arbeiten willst, solltest du stattdessen `dev:styles` ausführen. +Solange der Prozess läuft, werden die Stylesheets stets neu kompiliert, wenn du sie veränderst. + +Jetzt kannst du die eigentliche Webseite starten. +Dazu musst du zunächst den Namen des Unterordners von **sites/** notieren, der zu der Webseite passt, an der du arbeiten möchtest. +Diesen Namen schreibst du in die Umgebungsvariable `SITE`. +Anschließend kannst du den Server starten. +Hier beispielhaft für die Angestöpselt-Seite: + +```shell +# Unter Linux / Mac: +export SITE=angestoepselt +# Oder in der PowerShell (Windows): +$Env:SITE='angestoepselt' + +# Und dann im Anschluss: +npm run dev:site +``` + +## Deployment + +Der `main`-Zweig wird automatisch durch unseren [CI-Server](https://drone.z31.it) deployt. +Das bedeutet: **alles, was auf `main` ist, ist live**! +Hier sind die jeweiligen URLs: + +- Angestöpselt: [angestoepselt.de](https://angestoepselt.de/) +- CoderDojo: [coderdojo-wue.de](https://coderdojo-wue.de/) + +Das Deployment funktioniert via [Portainer](https://portainer.pub.z31.it). +Verwendet wird dazu die [docker-compose.yml](https://codeberg.org/angestoepselt/homepage/src/branch/main/docker-compose.yml) aus diesem Repository. + +### Konfiguration + +Damit das Docker-Deployment (auch lokal) funktioniert, müssen ein paar Umgebungsvariablen gesetzt sein. +Hier sind sie, zusammen mit ihren Standards: + +- `ZAMMAD_URL=https://ticket.z31.it` – Basis-URL der Zammad-Instanz, die durch die Kontaktformulare befüllt wird. +- `ZAMMAD_GROUP=""` – Ist diese Variable gesetzt (das ist sie in der Staging-Umgebung), landen alle Kontaktformular-Einträge in dieser Zammad-Gruppe. Standardmäßig (wenn dieser Wert leer ist) werden sie je nach Thema in die korrekte Gruppe einsortiert. +- `ZAMMAD_TOKEN` – API-Schlüssel zur Zammad-Instanz. Dieser Schlüssel muss die `ticket.agent`-Berechtigung haben. +- `HCAPTCHA_SITE_KEY` – Quasi-öffentlicher Schlüssel zum [Einbinden von hCaptcha](https://docs.hcaptcha.com/#add-the-hcaptcha-widget-to-your-webpage). +- `HCAPTCHA_SECRET_KEY` – Geheimer Schlüssel für die [Serverseitige Kontrolle der hCaptcha-Antworten](https://docs.hcaptcha.com/#verify-the-user-response-server-side). + +Die letzten drei sind pflicht. + +Wenn du das Image lokal bauen möchtest, musst du das [Argument](https://docs.docker.com/build/guide/build-args/) `SITE` mitgeben, genau wie bei der lokalen Entwicklung. + +## Staging-Umgebung + +Wir haben für die beiden großen Seiten jeweils eine Staging-Umgebung: + +- Angestöpselt: [csw.stage.angestoepselt.de](https://csw.stage.angestoepselt.de/) +- CoderDojo: [coderdojo.stage.angestoepselt.de](https://coderdojo.stage.angestoepselt.de/) + +## Workflow für Änderungen + +Wenn du deine Änderungen gerne online stellen möchtest, musst du einen [Pull-Request](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/) einreichen. +Ein Pull-Request bündelt deine Änderungen, sodass sie jemand vom Homepage-Team anschauen, genehmigen und einpflegen kann. + +Wenn du deine Änderungen über das Webinterface von Codeberg erstellst, wählst du beim Bearbeiten einer Datei im *Änderungen Commiten*-Dialog die Option "Einen neuen Branch für diesen Commit erstellen und einen Pull Request starten". +Wenn du anschließend in den Pull-Request noch eine weitere Änderung aufnehmen möchtest, sucher [hier](https://codeberg.org/angestoepselt/homepage/branches) deinen entsprechenden Branch und wähle ab der zweiten Bearbeitung in dem erwähnten Dialog "Direkt in den Branch `...` einchecken". + +Wenn du Mitglied des [Homepage](https://codeberg.org/org/angestoepselt/teams/homepage)-Teams auf Codeberg bist, kannst du ohne Forken direkt auf unserem Repository arbeiten. +Dann kannst du auch die Staging-Umgebung verwenden (siehe oben). +Falls du gerne Mitglied werden willst, melde dich bitte bei [Matthias](https://codeberg.org/matti) oder [Yannik](https://codeberg.org/yrd). +Du kannst auch hier im Projekt ein Issue erstellen. + +Du kannst so viele Pull-Requests gleichzeitig erstellen wie du magst (musst also nicht warten, bis der erste genehmigt ist). +Bitte erstelle einen neuen PR für jedes "Thema" das du anschneidest. +Aktuell kümmern sich [Matthias](https://codeberg.org/matti) und [Yannik](https://codeberg.org/yrd) um das Zusammenführen der PRs. diff --git a/README.md b/README.md index 61517da..fcb7ea6 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,42 @@ -# Angestöpselt Homepages +# Angestöpselt im Web -This repository mainly contains the next version of Angestöpselt's homepage, intended to be hosted at . -It is built with the [Eleventy](https://www.11ty.dev/) static site generator, using SCSS for stylesheets. -It also hosts the site for [CoderDojo Würzburg](https://coderdojo-wue.de). +Hallo! :wave: -## Project structure +Was du hier siehst, ist der Code für die wichtigen Internetauftritte von Angestöpselt. +Dazu zählen in erster Linie -The project's directory tree is structured as follows. -Note that this repository contains code to build different sites with some shared elements. +- unsere Homepage auf [angestoepselt.de](https://angestoepselt.de/) und +- die Seite zum CoderDojo-Projekt auf [coderdojo-wue.de](https://coderdojo-wue.de/). -- **assets/** – Shared static content. This will be copied into the `assets` directory when building any site. -- **cgi-bin/** – CGI scripts. These are shared between sites, but not every site makes use of all the scripts. Note that these should not be called directly by site visitors. Rather they are called by rewriting paths in the server configuration where appropriate. -- **includes/** – Directory for [Eleventy includes](https://www.11ty.dev/docs/config/#directory-for-includes). This contains layouts and template files. -- **nix/** – Auxiliary build files used by the [Nix](https://nixos.org/) package manager. -- **playground/** – This directory contains anything that shouldn't be included directly but might be relevant to the project. -- **sites/** – Each site gets a subdirectory here containing its content. - - **<name>** - - **\_static/** – Site-specific static content. - - **assets/** – Site-specific assets. This will be copied into the `assets` directory of the final output. - - **\_data/** – Directory for Eleventy [global data files](https://www.11ty.dev/docs/data-global/). - - **\_images/** – Place images that should be rendered by the build system in some way here. - - **httpd.conf** – Configuration file for [lighttpd](https://redmine.lighttpd.net/projects/lighttpd/wiki#Documentation), which will serve the final site. - - _Anything else_ is actual content for the site (usually in the form of markdown files). -- **styles/** – SCSS stylesheets. Anything directly in this directory that doesn't begin with an underscore will be available in the final build. -- **.eleventy.js** – Base Eleventy configuration. This is set up so that the correct paths for the selected site (according to the environment variable `SITE`) are selected automatically. -- **.eleventyignore** – Eleventy ignore file. Place paths in here that should be excluded in the final build. +Gebaut ist das Ganze mit [Eleventy](https://www.11ty.dev/). +Eleventy ist ein Programm, das aus einer Menge [Markdown](https://de.wikipedia.org/wiki/Markdown)-Dateien eine lauffähige Homepage baut. +Alle erwähnten Seiten verwenden die gleiche Basis, unterscheiden sich allerdings in ihrem Inhalt. -## Local development environment +### Ich möchte an der Homepage mitarbeiten. -To build the site locally, make sure you have Node installed (currently tested -with version 14). In Linux run: +Wir haben [hier](https://codeberg.org/angestoepselt/homepage/src/branch/main/CONTRIBUTING.md) eine etwas umfassendere Dokumentation zum Mitarbeiten. +Falls du es eilig hast, hier sind die Grundlagen: -```shell -npm install -npm run build:styles -SITE=angestoepselt npm run dev:site -``` -If you are using Windows, you need to use the following commands in PowerShell instead: -```shell -npm install -npm run build:styles -$Env:SITE='angestoepselt' -npm run dev:site -``` +1. Node in einer einigermaßen aktuellen Version installieren +2. Das Projekt auschecken, dann `npm install` +3. `npm run build:styles` +4. `SITE=angestoepselt npm run dev:site`1 + - Du solltest einen lokalen Testserver bekommen, der auf Änderungen reagiert. Formulare funktionieren hier nicht. + - Im Ordner **dist/** liegen die fertigen Dateien für den Webserver. +5. Änderungen in einem PR auf den `main`-Zweig einreichen +1: Wähle für die Umgebungsvariable den Namen des Ordners unterhalb von **sites/** für die Seite, die du bearbeiten möchtest. -Go to , which will update live when content changes -(the initial build may take some time to render out the different image sizes). -If you make style changes, make sure to recompile the CSS files with the second -of the above commands. Alternatively, run `npm run dev:styles` in an additional -terminal to watch for changes. +### Ich habe einen Fehler entdeckt oder habe einen Verbesserungsvorschlag. -### Nix environment +Falls du selbst ein Entwickler bist, kannst du auf hier auf Codeberg einen Fork des Projekts erstellen und einen Pull-Request einreichen. +Danke! -This repository also contains a [Nix flake](https://nixos.wiki/wiki/Flakes) -which contains the full development environment. `nix develop` will open a -shell with all required tools – you don't need to run `npm install` anymore. -Run `nix build ".#devEnv" -o .dev` to get a running Node environment in the -_.dev_ folder (for example to configure an IDE). +Falls nicht, schreibe uns gerne an [info@angestoepselt.de](mailto:info@angestoepselt.de) oder über unser [Kontaktformular](https://angestoepselt.de/kontakt/#andere-anliegen). -When Node dependencies are updated (this will change `package.json`), make sure -to run `./nix/update.sh` to update the npm lockfile and the Nix environment. +### Ich interessiere mich für den Code. -The flake also contains a second package for building the production output: +Dann bist du hier genau richtig. +Sieh dich ruhig ein wenig um! -```shell -nix build # Will create an output derivation in 'result' -``` - -## Deployment - -Deploy the container from the image automatically by the CI server. -Ask @yrd for the URL. - -The container will expose the site under port 80. -Further configuration is available via environment variables. - -- `ZAMMAD_URL=https://ticket.z31.it` – URL of the Zammad server to use. -- `ZAMMAD_GROUP=` – Set this variable to override the group all Zammad tickets go in. If empty (the default), different forms will be sorted into different groups. -- `ZAMMAD_TOKEN` – This is the only mandatory option. Set it to a Zammad access token with the `ticket.agent` permission. - -See https://codeberg.org/angestoepselt/homepage/issues/6#issuecomment-419104 for details. +Das Projekt ist [MIT-Lizenziert](https://codeberg.org/angestoepselt/homepage/src/branch/main/LICENSE).