Skip to content

Commit 5f8366f

Browse files
SandPodSandPod
committed
docs: Add contribution guidelines.
1 parent aa3d9c5 commit 5f8366f

File tree

1 file changed

+271
-0
lines changed

1 file changed

+271
-0
lines changed

‎CONTRIBUTING.md

+271
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# How to contribute to Serverpod
2+
3+
Serverpod is built by the community for the community. We welcome contributions from everyone, regardless of your experience level. This document will guide you through the process of contributing to the Serverpod project.
4+
5+
## Ways to contribute
6+
7+
There are multiple ways to contribute to the Serverpod project. Here are some of the most common ways:
8+
9+
- **Code**: Contribute code to the Serverpod project.
10+
- **Documentation**: Contribute to the Serverpod documentation.
11+
- **Support**: Help others with their Serverpod projects.
12+
- **File issues**: Suggest new features or improvements to Serverpod.
13+
14+
## Roadmap
15+
16+
Serverpod's [roadmap](https://github.com/orgs/serverpod/projects/4) outlines the features and improvements that are planned for the project. The roadmap is subject to change, but provides a good overview over what is being worked on and what is planned for the future.
17+
18+
If you are considering contributing code to Serverpod, please check the roadmap to see if your contribution aligns with the project's goals.
19+
20+
## Contributing code
21+
22+
Pull request are very much welcome. If you are working on something more significant than just a smaller bug fixes, please declare your interest on an issues first. This way we can discuss the changes to ensure that they align with the project's goals and prevent duplicated work.
23+
24+
A good starting point is to look at our list of [good first issues](https://github.com/serverpod/serverpod/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). These are issues that are relatively easy to fix and are a good way to get started with the project.
25+
26+
### Repository overview
27+
28+
Serverpod is a large project and contains many parts. Here is a quick overview of how Serverpod is structured and where to find relevant files required to contribute.
29+
30+
#### `packages`
31+
32+
Here, you find the core serverpod Dart packages.
33+
34+
- __`serverpod`__: Contains the main Serverpod package, the ORM, basic authentication, messaging, and cache. It also contains the endpoints of the Serverpod Insights API.
35+
- __`serverpod_client`__: Classes used by the generated client, these are not generated by the CLI tooling.
36+
- __`serverpod_flutter`__: Client code that relies on Flutter. It contains implementations of classes defined in `serverpod_client`.
37+
- __`serverpod_serialization`__: Code for handling serialization, which is shared between the `serverpod` package and `serverpod_client`.
38+
- __`serverpod_service_client`__: This is the generated API for Serverpod Insights.
39+
- __`serverpod_shared`__: Code that is shared between serverpod and Serverpod's tooling (i.e., `serverpod_cli`).
40+
- __`serverpod_test`__: Contains code used by the test framework.
41+
42+
#### `templates`
43+
44+
The templates directory contains templates for the project.
45+
46+
- __`serverpod_templates`__: Contains templates used when creating a new project with the `serverpod create` command.
47+
- __`pubspec_templates`__: Templates for the pubspec files in the repository. To generate the real pubspec files from the templates, use the `util/update_pubspecs` script.
48+
49+
#### `tools`
50+
51+
Here, you will find the code for Serverpod's tooling.
52+
53+
- __`serverpod_cli`__: Serverpod's command line interface. The CLI also contains code for Serverpod's analyzer and code generation.
54+
- __`serverpod_vs_code_extension`__: The VS Code extension is built around the CLI.
55+
56+
#### `modules`
57+
58+
These are 1st party modules for Serverpod. Currently, we maintain an authentication module and a chat module. Modules contain server, client, Flutter code, and definitions for database tables.
59+
60+
#### `integrations`
61+
62+
These are integrations for 3rd party services, such as Cloud storage.
63+
64+
#### `examples`
65+
66+
Here, you will find example projects that demonstrate how to use Serverpod.
67+
68+
#### `test`
69+
70+
This directory contains tests for the Serverpod project.
71+
72+
- __`boostrap_project`__: Test that validate all variations of a project can be created and run.
73+
- __`docker`__: Docker configuration required for running the tests.
74+
- __`serverpod_cli_e2e_test`__: End to end tests for the CLI.
75+
- __`serverpod_test_server`__: Contains tests that require a complete Serverpod project. The folder contains tests from both the client and server side.
76+
- __`serverpod_test_flutter`__: Contains tests for Flutter components used by the client.
77+
- __`serverpod_test_client`__: Tests that only required the client.
78+
- __`serverpod_test_module`__: General module tests.
79+
80+
### Setting up the development environment
81+
82+
There are some tools needed to be able to contribute to Serverpod. Below is a list of tools required to contribute to Serverpod.
83+
84+
- **Dart**: Serverpod is written in Dart, so you need to have Dart installed on your machine. You can download Dart from the [Dart website](https://dart.dev/get-dart).
85+
- **Flutter**: Some parts of the project require Flutter to be installed on your machine. You can download Flutter from the [Flutter website](https://flutter.dev/docs/get-started/install).
86+
- **Docker**: Some tests require Docker to be installed on your machine. You can download Docker from the [Docker website](https://www.docker.com/get-started).
87+
- **Git**: Serverpod is hosted on GitHub, so you need to have Git installed on your machine. You can download Git from the [Git website](https://git-scm.com/downloads).
88+
- **Melos**: Serverpod uses Melos to manage the monorepo. You can install Melos by running `pub global activate melos`.
89+
- **bash**: Some scripts require bash to be installed on your machine. If you are on Windows, you can install Git Bash from the [Git website](https://git-scm.com/downloads).
90+
91+
After the required tools have been installed, you will need to clone the repository.
92+
We recommend [forking](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the repository and then cloning your fork.
93+
94+
After the repository is cloned you should run the following command to install the dependencies:
95+
96+
```bash
97+
$ util/pub_get_all
98+
```
99+
100+
> [!TIP]
101+
> If you have recently configured a Serverpod project, you can add the `--offline` flag to the script above to use cached versions of the dependencies.
102+
103+
The project is now set up and ready for development.
104+
105+
### Activating the CLI
106+
107+
To run the `serverpod` command from your cloned repository, you will need to:
108+
109+
```bash
110+
$ cd tools/serverpod_cli
111+
$ dart pub get
112+
$ dart pub global activate --source path .
113+
```
114+
115+
Depending on your Dart version you may need to run the `dart pub global` command above every time you've made changes in the Serverpod tooling.
116+
117+
> [!TIP]
118+
> At the time of writing, a bug in `pub global activate` prevents changes from being picked up in activated libraries, tracked here: https://github.com/dart-lang/pub/issues/4295.
119+
>
120+
> If you are experiencing issues with the CLI not picking up changes, you can try running the workarounds listed in the issue.
121+
122+
123+
When projects are created using your cloned version of the CLI, all serverpod dependencies in the `pubspec.yaml` files will point to your cloned repo.
124+
125+
#### Using local templates
126+
127+
To use templates from your cloned repository, you will need to set the `SERVERPOD_HOME` environment variable. It should point to the root your cloned `serverpod` monorepo. (E.g. `/Users/myuser/MyRepos/serverpod`)
128+
129+
### Code style
130+
131+
Serverpod uses the Dart linter to enforce a consistent code style. The linter is run as part of the CI checks, so it is important that the code follows the linter rules. When you write code, make sure to use `dart format` and `dart analyze` to ensure that the code follows the linter rules.
132+
133+
We try to follow the [Effective Dart](https://dart.dev/guides/language/effective-dart) guidelines as much as possible. But above all we care about code readability and maintainability. Therefore, we encourage you to write code that is easy to read and understand for future contributors.
134+
135+
### Running the tests
136+
137+
Serverpod has a comprehensive test suite that covers the core functionality of the project. The tests are run as part of the CI checks, so to speed up development it can be good to run the tests locally before submitting a pull request. Scripts to run groups of tests are located in the `util` directory and their name starts with `run_tests`.
138+
139+
#### Test scripts
140+
141+
To run the tests, you can use the following scripts in the `util` directory:
142+
143+
| Script | Description |
144+
| --- | --- |
145+
| `run_tests_unit` | Run all unit tests. |
146+
| `run_tests_integration` | Run all non concurrent integration tests in the test project. |
147+
| `run_tests_integration_concurrently` | Run all concurrent integration tests in the test project. |
148+
| `run_tests_flutter_integration` | Run all Flutter integration tests in the flutter test project. |
149+
| `run_tests_e2e` | Run all server end to end tests in the test project. |
150+
| `run_tests_migrations_e2e` | Run all migration end to end tests. |
151+
| `run_tests_bootstrap` | Run all bootstrap tests. |
152+
| `run_tests_update_pubspecs` | Ensure that all pubspec files are up to date with the templates. |
153+
| `run_tests_analyze` | Run the code analysis tests. |
154+
| `run_tests_update_pubspecs` | Ensure that all pubspec files are up to date with the templates. |
155+
156+
As an example, running the unit tests can be done with the following command:
157+
158+
```bash
159+
$ util/run_tests_unit
160+
```
161+
162+
#### Running single test
163+
164+
All unit tests can be run with the `test` command. But for some tests, you may need to perform additional steps to set up the test environment. Listed below are the required steps to run tests that require additional setup.
165+
166+
167+
##### Running integration tests
168+
169+
To run any integration test in the `tests/serverpod_test_server/test_integration` directory you will need to follow these steps:
170+
171+
1. Start the Docker container for the test server.
172+
173+
```bash
174+
$ cd tests/serverpod_test_server/docker-local
175+
$ docker-compose up --build --detach
176+
```
177+
178+
2. Start the test server and apply migrations.
179+
180+
```bash
181+
$ cd tests/serverpod_test_server
182+
$ dart bin/main.dart --apply-migrations
183+
```
184+
185+
##### Running test project end to end test
186+
187+
To run end to end tests in the `tests/serverpod_test_server/test_e2e` directory, you will need to follow these steps:
188+
189+
1. Add entries for the test server, postgres and redis at the end of your `/etc/hosts file`.
190+
191+
```text
192+
127.0.0.1 serverpod_test_server
193+
127.0.0.1 postgres
194+
127.0.0.1 redis
195+
```
196+
197+
2. Start the Docker container for the test server.
198+
199+
```bash
200+
$ cd tests/serverpod_test_server/docker-local
201+
$ docker-compose up --build --detach
202+
```
203+
204+
3. Start the test server and apply migrations.
205+
206+
```bash
207+
$ cd tests/serverpod_test_server
208+
$ dart bin/main.dart --apply-migrations
209+
```
210+
211+
4. Run an individual test
212+
213+
```bash
214+
$ cd tests/serverpod_test_server
215+
$ dart test test_e2e/connection_test.dart
216+
```
217+
218+
##### Running test project migration tests
219+
220+
To run migration tests in the `tests/serverpod_test_server/test_e2e_migrations` directory, you will need to follow these steps:
221+
222+
1. Remove any existing test database.
223+
224+
```bash
225+
$ cd tests/serverpod_test_server/docker-local
226+
$ docker-compose down -v
227+
```
228+
229+
2. Start a new Docker container for the test server.
230+
231+
```bash
232+
$ cd tests/serverpod_test_server/docker-local
233+
$ docker-compose up --build --detach
234+
```
235+
236+
### Introducing new dependencies
237+
238+
Adding new dependencies to the project should be done with care. We are very restrictive with adding new dependencies to the project. If dependencies are added, they should be well maintained and have a good reason for being added.
239+
240+
Modifications to the `pubspec.yaml` files should be done in the templates directory. The `pubspec.yaml` files in the root of the repository are generated from the templates. After the templates have been modified, run the `util/update_pubspecs` script to update the `pubspec.yaml` files.
241+
242+
```bash
243+
$ util/update_pubspecs
244+
```
245+
246+
### Submitting a pull request
247+
248+
All pull requests should be submitted to the `main` branch. The pull request should contain a description of the changes and a reference to the issue that the pull request is addressing.
249+
250+
To keep the projects git history clean, we will squash PRs before merging. Therefore, it is essential that each pull request only contains a single feature or bug fix. Keeping pull requests small also makes it easier to review the changes which in turn speeds up the review process.
251+
252+
Before the Serverpod team can review your pull request, it must pass the CI checks. The CI checks include running the tests and the linter. If the CI checks fail, the pull request will not be reviewed.
253+
254+
We also require that all pull requests have a test that validates the changes. If the changes are not testable, please explain why in the pull request.
255+
256+
### Getting support
257+
258+
Feel free to post on Serverpod's discussion board if you have any questions. We check the board daily.
259+
260+
## Contributing documentation
261+
262+
Help us improve the Serverpod documentation by submitting pull requests to the [serverpod_docs](https://github.com/serverpod/serverpod_docs) repository.
263+
We have a list of [documentation](https://github.com/serverpod/serverpod/issues?q=is%3Aissue%20state%3Aopen%20label%3Adocumentation) issues that are a good starting point for contributing.
264+
265+
## Contributing support
266+
267+
We encourage you to help others with their Serverpod projects. You can do this by answering questions on the discussion board. You can also help by writing tutorials or blog posts about Serverpod and your experiences with the project.
268+
269+
## Contributing with issues
270+
271+
If you find a bug or have a feature request, please file an [issue](https://github.com/serverpod/serverpod/issues/new/choose).

0 commit comments

Comments
 (0)