diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..59f904670 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,31 @@ +# Martins documentation + +The documentation of `maplibre/martin` is available at . + +To build/develop this documentation locally, you can install `mdbook` and `mdbook-linkcheck`. + +```bash +cargo install mdbook +``` + +## Development + +You can simply edit the markdown files in the `src` directory and run the following command (from the project root directory) to preview the changes: + +```bash +mdbook watch --open docs +``` + +Next to showing you how the docs will look, this also runs a link checker to ensure that all links are valid. + +> [!TIP] +> Make sure that all pages are linked from [`src/SUMMARY.md`](src/SUMMARY.md). +> **Only** pages linked will be rendered. +> See the [mdbook documentation](https://rust-lang.github.io/mdBook/) for more information. + +> [!NOTE] +> Files may only be added, not renamed. +> If you want to rename a file, make sure to [add a redirect to the new file in `output.html.redirect`](https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect). +> Renaming files would otherwise break existing, external links for example on stackoverflow or github-discussions. +> +> Removing is bad for the same reasons and will be handled on a case-by-case basis. diff --git a/docs/src/development.md b/docs/src/development.md index 1224ad071..eaf7db673 100644 --- a/docs/src/development.md +++ b/docs/src/development.md @@ -1,33 +1,108 @@ # Development -Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest -changes from the upstream repo. +## Git setup -```bash, ignore -git clone https://github.com/maplibre/martin.git -o upstream +The recommended setup for both core and casual contributors is to **always** create a fork +of the primary repo under their own account. The local repo should have two remotes: `upstream` pointing to the primary `maplibre/martin` repo, and `origin` pointing to the user's own fork. The `main` branch should track `upstream/main`, but all new work will be pushed to `origin` and PRs will be created from there. + +
Rationale for this setup (click to expand) + +This rationale was copied from [a post](https://gist.github.com/nyurik/4e299ad832fd2dd43d2b27191ed3ec30) by Yuri + +Open source contribution is both a technical and a social phenomenon. +Any FOSS project naturally has a "caste system" - a group +of contributors with extensive rights vs everyone else. Some of this separation +is necessary - core contributors have deeper knowledge of the code, share vision, +and trust each other. + +Core contributors have one more right that others do not -- they can create repository branches. +Thus, they can contribute "locally" - by pushing proposed changes to the primary repository's work branches, +and create "local" pull requests inside the same repo. This is different from others, +who can contribute only from their own forks. + +There is little difference between creating pull requests from one's own fork and from the primary repo, +and there are a few reasons why core contributors should **never** do it from the primary repo: + +* it ensures that casual contributors always run the same CI as core contributors. If contribution process breaks, it will affect everyone, and will get fixed faster. +* it puts everyone on the same leveled playing field, reducing the "caste system" effect, making the project feel more welcoming to new contributors +* it ensures that the primary repo only has maintained branches (e.g. `main` and `v1.x`), + not a bunch of PR branches whose ownership and work status is unclear to everyone + +In the martin repository, we follow this and have a branch protection rule that prevents core contributors from creating pull requests from the primary repo. + +
+ +```bash +# clone the primary fork to your local machine, naming the remote "upstream" +# make sure to replace the URL with the correct one +git clone -o upstream https://github.com/maplibre/martin.git cd martin + +# add your own fork as a remote, naming it "origin" +git remote add origin https://github.com/nyurik/martin.git ``` -Fork Martin repo into your own GitHub account, and add your fork as a remote +For further setup instructions for IDEs, please see the [Getting Involved](getting-involved.md) step after you have installed the necessary tools below. +
If you have already cloned the repo locally, use this guide to update your setup (click to expand) -```bash, ignore -git remote add origin _URL_OF_YOUR_FORK_ +If you already cloned the repo locally, you can update it to use the new setup. This assumes you have a local clone of the repo, the remote name is `origin`, and you have already forked the repo on GitHub. + +```bash +# Getting a quick glance about your remotes: git remote -v +git remote -v +# Rename the existing remote to "upstream". Your "main" branch will now track "upstream/main" +git remote rename origin upstream + +# Add your own fork as a remote, naming it "origin" (adjust the URL) +git remote add origin https://github.com/nyurik/martin.git ``` -Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/) +
-```bash, ignore -# Ubuntu-based distros have an older version that might also work: -sudo apt install -y docker.io docker-compose +### Contributing New Code + +```bash +# switch to main branch (tracking upstream/main), and pull the latest changes +git switch main +git fetch upstream + +# create a new branch for your work +git switch -c my-new-feature + +# edit files, and commit changes +# '-a' will add all modified files +# `-m` allows you to add a short commit message +git commit -a -m "My new feature" + +# push the changes to your own fork +# '-u' will track your local branch with the remote +git push -u origin my-new-feature + +# Click the link shown by `git push` in the terminal to create a pull request +# from your fork using the GitHub web interface ``` +## Installed tools and libraries + Install a few required libs and tools: ```bash, ignore # For Ubuntu-based distros -sudo apt install -y build-essential pkg-config jq file gdal-bin +sudo apt update +sudo apt install -y build-essential pkg-config jq file gdal-bin +``` + +### docker + +Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/) + +```bash, ignore +# Ubuntu-based distros have an older version that might also work: +sudo apt install -y docker.io docker-compose ``` +### just + Install [Just](https://github.com/casey/just#readme) (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: diff --git a/docs/src/martin-as-a-library.md b/docs/src/martin-as-a-library.md index 680d2435e..d094fbbb4 100644 --- a/docs/src/martin-as-a-library.md +++ b/docs/src/martin-as-a-library.md @@ -2,8 +2,16 @@ Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: -* **postgres** - enable PostgreSQL/PostGIS tile sources -* **pmtiles** - enable PMTile tile sources -* **mbtiles** - enable MBTile tile sources -* **fonts** - enable font sources -* **sprites** - enable sprite sources +* `webui` - enable web UI +* tile sources + * `mbtiles` - enable MBTile tile sources + * `pmtiles` - enable PMTile tile sources + * `postgres` - enable PostgreSQL/PostGIS tile sources +* supporting resources + * `fonts` - enable font sources + * `sprites` - enable sprite sources + * `styles` - enable style sources +* `lambda` - add specialised support for running in serverless functions + +If you are missing a part of Martin functionality in the [public `martin` API](https://docs.rs/martin), we would love to hear from you. +Please open an issue on our GitHub repository or directly open a pull request.