Skip to content

Commit 048592c

Browse files
SandPodSandPod
committed
docs: Add contribution guidelines.
1 parent aa3d9c5 commit 048592c

File tree

1 file changed

+269
-0
lines changed

1 file changed

+269
-0
lines changed

‎CONTRIBUTING.md

+269
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
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 get started or expand 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 work in progress 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+
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**: Docker is used to run Postgres and Redis for the development environment. 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 a local clone of 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, run the following command to install all 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+
Activate the `serverpod` command from your cloned repository by running the following commands:
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.
138+
139+
To ensure all tests work as expected, it is recommended to add an entry for the test server, postgres and redis at the end of your `/etc/hosts file`.
140+
```text
141+
127.0.0.1 serverpod_test_server
142+
127.0.0.1 postgres
143+
127.0.0.1 redis
144+
```
145+
146+
#### Test scripts
147+
148+
Scripts that run groups of tests are located in the `util` directory and their name start with `run_tests`. The following test scripts are available:
149+
150+
| Script | Description |
151+
| --- | --- |
152+
| `run_tests_unit` | Run all unit tests. |
153+
| `run_tests_integration` | Run all non concurrent integration tests in the test project. |
154+
| `run_tests_integration_concurrently` | Run all concurrent integration tests in the test project. |
155+
| `run_tests_flutter_integration` | Run all Flutter integration tests in the flutter test project. |
156+
| `run_tests_e2e` | Run all server end to end tests in the test project. |
157+
| `run_tests_migrations_e2e` | Run all migration end to end tests. |
158+
| `run_tests_bootstrap` | Run all bootstrap tests. |
159+
| `run_tests_update_pubspecs` | Ensure that all pubspec files are up to date with the templates. |
160+
| `run_tests_analyze` | Run the code analysis tests. |
161+
| `run_tests_update_pubspecs` | Ensure that all pubspec files are up to date with the templates. |
162+
163+
To run any script, navigate to the root of the repository and run the script, e.g.:
164+
165+
```bash
166+
$ util/run_tests_unit
167+
```
168+
169+
#### Running single tests
170+
171+
All unit tests can be run with the `test` command. But for some tests, you may need to perform additional steps to set up a test environment. Listed below are the tests that require additional setup.
172+
173+
##### Running integration tests
174+
175+
To run any integration test in the `tests/serverpod_test_server/test_integration` directory you will need to follow these steps:
176+
177+
1. Start the Docker container for the test server.
178+
179+
```bash
180+
$ cd tests/serverpod_test_server/docker-local
181+
$ docker-compose up --build --detach
182+
```
183+
184+
2. Start the test server and apply migrations.
185+
186+
```bash
187+
$ cd tests/serverpod_test_server
188+
$ dart bin/main.dart --apply-migrations
189+
```
190+
191+
##### Running test project end to end tests
192+
193+
To run end to end tests in the `tests/serverpod_test_server/test_e2e` directory, you will need to follow these steps:
194+
195+
1. Start the Docker container for the test server.
196+
197+
```bash
198+
$ cd tests/serverpod_test_server/docker-local
199+
$ docker-compose up --build --detach
200+
```
201+
202+
2. Start the test server and apply migrations.
203+
204+
```bash
205+
$ cd tests/serverpod_test_server
206+
$ dart bin/main.dart --apply-migrations
207+
```
208+
209+
3. Run an individual test
210+
211+
```bash
212+
$ cd tests/serverpod_test_server
213+
$ dart test test_e2e/connection_test.dart
214+
```
215+
216+
##### Running test project migration tests
217+
218+
To run migration tests in the `tests/serverpod_test_server/test_e2e_migrations` directory, you will need to follow these steps:
219+
220+
1. Remove any existing test database.
221+
222+
```bash
223+
$ cd tests/serverpod_test_server/docker-local
224+
$ docker-compose down -v
225+
```
226+
227+
2. Start a new Docker container for the test server.
228+
229+
```bash
230+
$ cd tests/serverpod_test_server/docker-local
231+
$ docker-compose up --build --detach
232+
```
233+
234+
### Introducing new dependencies
235+
236+
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.
237+
238+
Modifications to `pubspec.yaml` files should be done in the templates directory. The `pubspec.yaml` files for all libraries are generated from these templates. After a templates has been modified, run the `util/update_pubspecs` script to update the `pubspec.yaml` files.
239+
240+
```bash
241+
$ util/update_pubspecs
242+
```
243+
244+
### Submitting a pull request
245+
246+
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.
247+
248+
All code changes should come with tests that validate the changes. If the changes are not testable, please explain why in the pull request.
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. If the CI checks fail, the pull request will not be reviewed.
253+
254+
### Getting support
255+
256+
Feel free to post on Serverpod's discussion board if you have any questions. We check the board daily.
257+
258+
## Contributing documentation
259+
260+
Help us improve the Serverpod documentation by submitting pull requests to the [serverpod_docs](https://github.com/serverpod/serverpod_docs) repository.
261+
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.
262+
263+
## Contributing support
264+
265+
We encourage you to support others in their Serverpod projects by sharing your knowledge and experiences. You can help by answering questions on the discussion board, participating in conversations on filed issues, or contributing your insights through tutorials and blog posts about Serverpod.
266+
267+
## Contributing with issues
268+
269+
Help us make Serverpod better by filing [issue](https://github.com/serverpod/serverpod/issues/new/choose) for bugs, feature requests, or improvements. When filing an issue, please provide as much information as possible to help us understand the problem or suggestion.

0 commit comments

Comments
 (0)