From 8fcfb502cab9cb21a7a29714c998c0dea7fbb000 Mon Sep 17 00:00:00 2001 From: Henrique Dias Date: Thu, 13 Nov 2025 17:16:50 +0100 Subject: [PATCH] docs: improve contribution documentation (#5540) --- CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++++++++------- Taskfile.yml | 25 ++++++++++++------- frontend/assets_dev.go | 14 ----------- http/headers_dev.go | 14 ----------- 4 files changed, 62 insertions(+), 46 deletions(-) delete mode 100644 frontend/assets_dev.go delete mode 100644 http/headers_dev.go diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1cfc8a92..d6e694f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,11 +15,23 @@ We encourage you to use git to manage your fork. To clone the main repository, j git clone https://github.com/filebrowser/filebrowser ``` +We use [Taskfile](https://taskfile.dev/) to manage the different processes (building, releasing, etc) automatically. + ## Build +You can fully build the project in order to produce a binary by running: + +```bash +task build +``` + +## Development + +For development, there are a few things to have in mind. + ### Frontend -We are using [Node.js](https://nodejs.org/en/) on the frontend to manage the build process. The steps to build it are: +We use [Node.js](https://nodejs.org/en/) on the frontend to manage the build process. Prepare the frontend environment: ```bash # From the root of the repo, go to frontend/ @@ -27,37 +39,62 @@ cd frontend # Install the dependencies pnpm install +``` -# Build the frontend +If you just want to develop the backend, you can create a static build of the frontend: + +```bash pnpm run build ``` -This will install the dependencies and build the frontend so you can then embed it into the Go app. Although, if you want to play with it, you'll get bored of building it after every change you do. So, you can run the command below to watch for changes: +If you want to develop the frontend, start a development server which watches for changes: ```bash pnpm run dev ``` +Please note that you need to access File Browser's interface through the development server of the frontend. + ### Backend -First of all, you need to download the required dependencies. We are using the built-in `go mod` tool for dependency management. To get the modules, run: +First prepare the backend environment by downloading all required dependencies: ```bash go mod download ``` -The magic of File Browser is that the static assets are bundled into the final binary. For that, we use [Go embed.FS](https://golang.org/pkg/embed/). The files from `frontend/dist` will be embedded during the build process. - -To build File Browser is just like any other Go program: +You can now build or run File Browser as any other Go project: ```bash +# Build go build + +# Run +go run . ``` -To create a development build use the "dev" tag, this way the content inside the frontend folder will not be embedded in the binary but will be reloaded at every change: +## Documentation + +We rely on Docker to abstract all the dependencies required for building the documentation. + +To build the documentation to `www/public`: ```bash -go build -tags dev +task docs +``` + +To start a local server on port `8000` to view the built documentation: + +```bash +task docs-serve +``` + +## Release + +To make a release, just run: + +```bash +task release ``` ## Translations diff --git a/Taskfile.yml b/Taskfile.yml index 7a49d1fd..9721317f 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -33,17 +33,24 @@ tasks: - task: build-frontend - task: build-backend + release-make: + internal: true + prompt: Do you wish to proceed? + cmds: + - pnpm dlx commit-and-tag-version -s + + release-dry-run: + internal: true + cmds: + - pnpm dlx commit-and-tag-version --dry-run --skip + release: desc: Create a new release cmds: - - pnpm dlx commit-and-tag-version -s - - release-dry-run: - desc: Perform a dry run of the release - cmds: - - pnpm dlx commit-and-tag-version -dry-run --skip + - task: release-dry-run + - task: release-make - make-docs-image: + docs-image-make: internal: true cmds: - docker build -f www/Dockerfile --progress=plain -t filebrowser.site www @@ -52,11 +59,11 @@ tasks: desc: Generate documentation cmds: - rm -rf www/public - - task: make-docs-image + - task: docs-image-make - docker run --rm {{.SITE_DOCKER_FLAGS}} filebrowser.site build -d "public" docs-serve: desc: Serve documentation cmds: - - task: make-docs-image + - task: docs-image-make - docker run --rm -it -p 8000:8000 {{.SITE_DOCKER_FLAGS}} filebrowser.site diff --git a/frontend/assets_dev.go b/frontend/assets_dev.go deleted file mode 100644 index 01938ebe..00000000 --- a/frontend/assets_dev.go +++ /dev/null @@ -1,14 +0,0 @@ -//go:build dev - -package frontend - -import ( - "io/fs" - "os" -) - -var assets fs.FS = os.DirFS("frontend") - -func Assets() fs.FS { - return assets -} diff --git a/http/headers_dev.go b/http/headers_dev.go deleted file mode 100644 index 8ef7824f..00000000 --- a/http/headers_dev.go +++ /dev/null @@ -1,14 +0,0 @@ -//go:build dev - -package http - -// global headers to append to every response -// cross-origin headers are necessary to be able to -// access them from a different URL during development -var globalHeaders = map[string]string{ - "Cache-Control": "no-cache, no-store, must-revalidate", - "Access-Control-Allow-Origin": "*", - "Access-Control-Allow-Headers": "*", - "Access-Control-Allow-Methods": "*", - "Access-Control-Allow-Credentials": "true", -}