This guide helps developers understand how to contribute code, documentation, tests, and feedback to the Artalk project. We welcome all forms of contributions, whether it's large feature development, small fixes, documentation improvements, or testing. We believe that every contribution is an important part of moving the project forward.
This guide is available in multiple languages: English • 简体中文
Clone the repository:
git clone https://github.com/ArtalkJS/Artalk.git
It's recommended to fork the repository first, and then clone the forked repository.
Navigate to the directory:
cd Artalk
To develop Artalk, both frontend and backend, install the following tools:
- Node.js (>= 20.16.0)
- PNPM (>= 9.7.1)
- Go (>= 1.22)
- Docker (>= 20.10.0) (optional)
- Docker Compose (>= 1.29.0) (optional)
The development workflow consists of the following steps:
-
Set Up Complete Development Instance:
- Navigate to the Artalk Repo directory.
- Execute
make dev
to run the backend on port23366
. - Execute
pnpm dev
to run the frontend on port5173
. - Optionally, execute
pnpm dev:sidebar
to run the sidebar frontend on port23367
.
-
Access Frontend for Development:
- Open your browser and go to
http://localhost:5173
to perform your development and testing.
- Open your browser and go to
-
Testing:
- Run the backend unit tests using
make test
. - Run the ui unit tests using
pnpm test
. - Run the ui E2E tests using
make test-frontend-e2e
.
- Run the backend unit tests using
-
Building Frontend Code:
- When you make changes to the frontend code, build the complete frontend program using
pnpm build:all
. - The JavaScript and CSS code will be found in
ui/artalk/dist
. - The frontend code is automatically deployed to NPM by GitHub Actions.
- When you make changes to the frontend code, build the complete frontend program using
-
Building Backend Code:
- When you make changes to the backend code, note that the backend program embeds the frontend code.
- Before building the backend, run
make build-frontend
(which runsscripts/build-frontend.sh
). This will place the embedded frontend main program and sidebar frontend program in/public
. - Then, build the backend program using
make build
.
More exploration:
-
Developing Artalk Plugins or Themes: Refer to the Artalk Plugin Development Guide.
-
Makefile: You can explore the process and commands in the
Makefile
. -
Automated CI on GitHub: The automated CI pipeline on GitHub, located in the
.github/workflows
directory, builds the frontend, backend, and Docker images. It publishes Docker images to Docker Hub, handles npm package publishing, and creates GitHub Releases. And also testing the frontend and backend.
The following sections provide more detailed information on the development workflow.
Artalk is a monorepo project, meaning all the source code resides in a single repository. Despite this, the frontend and backend are kept separate. The frontend part is located in the ./ui
directory.
bin/
: The compiled binary files. (This directory is ignored by git).cmd/
: The source code for the command line tools.conf/
: The sample configuration files.data/
: The local data. (This directory is ignored by git).docs/
: The documentation site source code.i18n/
: The translation files.local/
: The local files. (This directory is ignored by git).internal/
: The Go source code for the internal packages.public/
: The static files. Built frontend files will be copied here.scripts/
: The scripts for development and building.server/
: The Go source code for the backend.ui/
: The UI source code for the frontend..github/
: The GitHub Actions workflows..vscode/
: The VSCode settings.
-
Create Configuration File:
- Copy
./conf/artalk.example.yml
to the root directory. - Rename it to
artalk.yml
. - Modify the file as needed.
- Copy
-
Start Backend Program:
- Run
make dev
to start the backend on port23366
. - Access it via
http://localhost:23366
. - It's recommended to keep the default port for testing.
- (Alternative) Use
ARGS="version" make dev
to pass startup parameters (default isARGS="server"
).
- Run
The make dev
builds the backend with debugging symbols, which is convenient for debugging with GDB.
If you are using the VSCode, you can use the F5
key (or RUN button) to start debugging the backend program directly.
-
Fetch Latest Git Tag: Execute
git fetch --tags
to get the latest git tag information. This tag will be used as the version number of the backend app. Alternatively, specify it using environment variables:VERSION="v1.0.0"
andCOMMIT_HASH="66128e"
. -
Build Frontend: Run
make build-fronted
to build the frontend, as the backend app embeds the frontend code. -
Build Backend: Execute
make build
to build the backend program.
The built binary file will be located in the ./bin
directory.
-
Install Dependencies:
Runpnpm install
to install all necessary dependencies. -
Start Development Server:
Executepnpm dev --port 5173
to start the frontend development server. -
Access the Frontend:
The frontend application will run on port5173
by default. Access it in your browser athttp://localhost:5173
. -
Sidebar Development:
To run the sidebar part of the frontend, usepnpm dev:sidebar
.
The ports 5173
and 23367
are used for frontend development and testing. These ports are included in the ATK_TRUSTED_DOMAINS
configuration of the backend program.
To build the frontend, run the following command:
make build-frontend
The compiled JavaScript and CSS files will be located in the /public
directory, embedded into the backend program.
For more details, refer to the scripts/build-frontend.sh
script.
To build the Docker image, run the following command:
docker build -t artalk:TAG .
Replace TAG
with the desired tag name (e.g., latest
).
If you have already built the frontend outside the Docker container, you can skip the frontend build process inside the container to speed up the build. Use the following command:
docker build --build-arg SKIP_FRONTEND_BUILD=true -t artalk:latest .
For more details, refer to the Dockerfile
.
To test the backend Go program, you can use the following commands:
-
Unit Testing: Run
make test
to execute unit tests. The results will be outputted in the terminal. -
Test Coverage: Run
make test-coverage
to check the code test coverage. -
HTML Coverage Report: Run
make test-coverage-html
to generate and browse the test coverage report in HTML format. -
Run Specific Tests: To run specific tests, use the command with an environment variable:
TEST_PATHS="./server/..." make test
Frontend testing includes unit tests and end-to-end (E2E) tests.
-
Unit Testing: The unit tests for the frontend are conducted using Vitest. Run
pnpm test
to start the unit testing. -
End-to-End Testing: E2E testing is conducted using Playwright. To start the E2E testing, run:
make test-frontend-e2e
Both frontend and backend testing are automated and will be performed during Git pull requests and as part of the build process using CircleCI or GitHub Actions.
The template configuration files are located in the /conf
directory, with templates annotated in multiple languages named in the format artalk.example.[lang].yml
(e.g., artalk.example.zh-CN.yml
). Artalk will parse these template configuration files to generate the settings interface, environment variable names, and documentation. To improve performance, some data will be cached during the program's runtime to eliminate parsing time.
In the internal/config/config.go
file, there is a definition of the Config
struct, which is used to parse the yml files into Go structs. This struct contains more precise type definitions. If you need to add, modify, or delete a configuration item, you must make changes to both the configuration file templates in /conf
and the Config
struct.
When you modify the configuration files, please run the following command to update the configuration data cache:
make update-conf
To update the environment variable documentation, you can run the command:
make update-conf-docs
The documentation consists of three parts, each associated with a specific package: Guide documentation, Landing page, and Swagger API documentation. Below is an organized summary of the relevant commands and their outputs for each package.
- Directory:
docs/docs/guide
- Dev Command:
pnpm -F docs dev:docs
- Build Command:
pnpm -F docs build:docs
- Output Directory:
docs/docs/.vitepress/dist
- Directory:
docs/landing
- Dev Command:
pnpm -F docs-landing dev:landing
- Build Command:
pnpm -F docs-landing build:landing
- Output Directory:
docs/landing/dist
- Directory:
docs/swagger
- Build Command:
make update-swagger
- Output Directory:
docs/swagger
Swagger definitions are located in the backend code at /server
. After modifying the Swagger definitions, running the build command will update the Swagger docs and generate HTTP client code at /ui/artalk/src/api/v2.ts
.
- Command to Build All Packages:
pnpm build:docs
- Combined Output Directory:
docs/docs/.vitepress/dist
This command builds and combines all three packages into a single directory, ready for publishing.
- File:
docs/docs/guide/env.md
- Command to Update:
make update-conf-docs
This command reads the configuration template file located in /conf
to update the environment variable documentation. Run this command after modifying the configuration template file.
If you write new features or make fixes/refactoring, use the following command to incrementally generate the translation files by parsing the source code for i18n.T
function calls:
make update-i18n
If you're not a programmer and would like to help improve the translation, you can edit the translation files directly in the /i18n
directory and then submit a pull request.
Thank you for your patience in reading this and for your interest and support in Artalk. We understand that the success of an open-source project relies on the contributions of every developer. Whether through code, documentation, testing, or feedback, your participation is the driving force behind the project's continuous progress. We sincerely invite you to join us in improving and enhancing Artalk.
By collaborating, we can create a more robust and versatile platform that benefits the entire community. Your unique insights and expertise are invaluable, and together, we can achieve remarkable advancements. Whether you are a seasoned developer or just starting, there is always a place for your contributions in our project.
If you have any questions or need assistance, please feel free to ask in the issue section on our GitHub page: https://github.com/ArtalkJS/Artalk/issues. Thank you once again for your support, and we look forward to working with you.