# Description of Changes
(jdetter): Github marked Ryan's PR as merged because I rebased it
without updating the base branch first - my bad.
Original PR: https://github.com/clockworklabs/SpacetimeDB/pull/4120
This PR fixes C#-related CI failures when testing against `v1.12.0`
before the corresponding NuGet packages are available on nuget.org.
* CI: Ensure local C# NuGet packages are used consistently
* Pack `crates/bindings-csharp/{BSATN.Runtime,Runtime}` with `-c
Release` so the configured local package sources (`bin/Release`)
actually contain the `.nupkg`s.
* Run `./sdks/csharp/tools~/write-nuget-config.sh` in CI to generate a
`NuGet.Config` that maps `SpacetimeDB.BSATN.Runtime` /
`SpacetimeDB.Runtime` to those local sources (with `nuget.org` as
fallback for non-SpacetimeDB dependencies).
* Add an explicit `dotnet restore --configfile NuGet.Config` step before
tests, and `run dotnet test --no-restore`, so restore always uses the
intended config and does not “accidentally” restore from `nuget.org`.
* `write-nuget-config.sh`: Make NuGet config discovery + mapping
deterministic
* Write `NuGet.Config` (capitalized) and include `<clear />` + an
explicit `nuget.org` source to avoid inherited sources and to keep
`PackageSourceMapping` functional.
* Also write a repo-root `NuGet.Config` so `dotnet publish/pack` invoked
from templates (outside `sdks/csharp/`) still discovers the same
override behavior.
* Smoketests quickstart: avoid `PackageSourceMapping` restore failures
* Ensure smoketest helper packing uses `Release`, and when repo-root
`NuGet.Config` exists, perform `dotnet restore --configfile ...` +
`dotnet pack --no-restore` so pack/restore are evaluated with the same
sources/mapping.
* When editing configs, prefer `NuGet.Config` casing for Linux discovery
and ensure `nuget.org` exists as a source for the fallback mapping.
# API and ABI breaking changes
No changes
# Expected complexity level and risk
1
# Testing
- [X] Locally tested concept after simulating local repro.
- [x] Confirmed CI passes in this branch
---------
Co-authored-by: rekhoff <r.ekhoff@clockworklabs.io>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
This PR does several small things:
1. It removes the explicit `h1` tags on every page, and either uses the
side bar title directly, or puts it in the frontmatter
2. It merges what are currently called quickstarts into a single Chat
App Tutorial
3. It creates new quickstarts which just use `spacetime dev --template`
to get you up and running quickly
4. It adds a "The Zen of SpacetimeDB" page much like the Zen of Python
which goes over the 5 key principles of SpacetimeDB
5. It reorders all Tabs groups so that the ordering is `TypeScript`,
`C#`, `Rust`, `Unreal`, `C++`, `Blueprints` (order of decreasing
popularity).
6. It improves the sidebar navigation by having categories act as
overview pages, and also fixes the breadcrumbs
7. It fixes various small typos and issues
8. Closes#3610 and adds cursor rules files generally
9. It fixes general styling on the docs page by bring it inline with the
UI design:
Old:
<img width="1678" height="958" alt="image"
src="https://github.com/user-attachments/assets/f36efee6-b81a-4463-a179-da68b3a7152e"
/>
New:
<img width="1678" height="957" alt="image"
src="https://github.com/user-attachments/assets/f430f77d-0663-47f2-9727-45cbfe10e4c7"
/>
https://github.com/user-attachments/assets/adc5a78a-ada8-45b5-8078-a45cb81477a3
# API and ABI breaking changes
This PR does NOT change any old links. It does add new pages though.
# Expected complexity level and risk
3 - it's a large change. I manually tested the TypeScript Chat App
Tutorial but I have not gone through the Rust and C# quickstarts.
However, we have testing on the quickstarts and this is text only so can
be carefully reviewed.
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Ran through each step of the Chat App TypeScript tutorial to
ensure it is working
- [x] Ran and tested the styles and the functionality of the side bar
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: spacetimedb-bot <spacetimedb-bot@users.noreply.github.com>
Co-authored-by: clockworklabs-bot <clockworklabs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
# Description of Changes
Closes: #3895
- Added third tier expanding folder
- Merged most into intro + core concepts
- Collapsed modules + database into one
- Moved several documents to how-to to streamline the core concepts
- Added warning to RLS to use views
- refactored all links
- Moved How To and References into Developer Resources
- Fixed TypeScript View code
Sample: (Getting Started will start expanded due to being the initial
page)
<img width="293" height="746" alt="image"
src="https://github.com/user-attachments/assets/6abc3a0d-1ae2-4886-bda7-11f5565afecf"
/>
# API and ABI breaking changes
N/A
# Expected complexity level and risk
1
# Testing
- [X] Updated the quickstarts.py and generate-cli tooling
---------
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
# Description of Changes
This makes it possible to insert new pages between existing pages
without renaming the existing pages.
I also added a section to docs/README.md with procedure for how to name
new pages, which I'll paste here:
### Adding new pages
All of our directory and file names are prefixed with a five-digit
number which determines how they're sorted.
We started with the hundreds place as the smallest significant digit, to
allow using the tens and ones places to add new pages between.
When adding a new page in between two existing pages, choose a number
which:
- Doesn't use any more significant figures than it needs to.
- Is approximately halfway between the previous and next page.
For example, if you want to add a new page between `00300-foo` and
`00400-bar`, name it `00350-baz`. To add a new page between `00350-baz`
and `00400-bar`, prefer `00370-quux` or `00380-quux`, rather than
`00375-quux`, to avoid populating the ones place.
To add a new page after all previous pages, use the smallest multiple of
100 larger than all other pages. For example, if the highest-numbered
existing page is `01350-abc`, create `01400-def`.
# API and ABI breaking changes
N/a
# Expected complexity level and risk
1 - @JulienLavocat said this wouldn't break anything.
# Testing
None.
---------
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
# Description of Changes
This PR is the first in a series of PRs which are an effort the
reorganize the docs and make it easier for people to get started using
SpacetimeDB.
This PR:
1. Renames all folders to be `kebab-case`. This is because `docIds` are
set based on folder and file names, and there is no way to override that
within a file (all you can change with `id: my-id` is the last component
of the id. Because we want to be able to access docs in react components
we need stable predictable ids.
- This also necessitates setting up a few `_category_.json` files so
that the categories do not show up as kebab case in the sidebar.
2. Adds a few React components with images so it's clearer on how to get
started
3. Reorganizes the quickstarts to be at the top of the side bar and
simplifies the server and client into a single document named for the
language
4. Sets up redirections so the old links to the old documents now point
to the new documents
5. Copies the entirety of `typography.css` from the website into this
repo for the purpose of keeping them identical
6. Makes minor fixes and improvements to the contents of the docs
In a future PR, I intend to:
1. Add a tutorial section to the docs which will include two tutorials:
Blackholio and Chat
2. Turn the chat quickstart documents into the Chat tutorial and
consolidate it into a single file with different language switchers (if
this is feasible)
3. Create a new quickstart section, which has a quickstart guide for
each platform that we support so far, namely:
- Vanilla TypeScript
- Vanilla JavaScript
- Vanilla Rust
- Vanilla C#
- React
- Unity
- Unreal
4. Update the quickstart guides to do the following (in the future I
will add more platforms with this scheme):
- Use `spacetime dev --template <framework-template>` to create a new
project for the given framework
- Insert data into the database
- Add a new `reducer` to the template
- Add a new `table` to the template
- Add a new `view` to the template
- Call the reducer from the client
- Subscribe to the `view` from the template
5. Break up the current per language module reference files into files
about SpacetimeDB concepts with a `TabGroup` for each language, namely:
- Modules
- Tables
- Reducers
- Procedures
- Code generation
- DbConnection (and the SDK API)
- Auth
- etc.
The idea being that we should explain our platform by concept, not by
language. This will also allow us to reuse a lot of prose that is
repeated in the different language documents.
# API and ABI breaking changes
None
# Expected complexity level and risk
1
# Testing
- [x] Tested the documents locally to ensure that they render properly
---------
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Fixes the issue described in
https://github.com/clockworklabs/SpacetimeDB/issues/3558.
# API and ABI breaking changes
None. CI only.
# Expected complexity level and risk
1
# Testing
- [x] Smoketests are now successful after running `cargo bump-versions
1.8.0 --typescript`.
---------
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Based on #3461, which fixes a bug encountered in the quickstart.
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
n/a
# Expected complexity level and risk
<!--
How complicated do you think these changes are? Grade on a scale from 1
to 5,
where 1 is a trivial change, and 5 is a deep-reaching and complex
change.
This complexity rating applies not only to the complexity apparent in
the diff,
but also to its interactions with existing and future code.
If you answered more than a 2, explain what is complex about the PR,
and what other components it interacts with in potentially concerning
ways. -->
1
# Testing
<!-- Describe any testing you've done, and any testing you'd like your
reviewers to do,
so that you're confident that all the changes work as expected! -->
- [x] Yes
- [ ] <!-- maybe a test you want a reviewer to do, so they can check it
off when they're satisfied. -->
This is a draft of the new functionality for `spacetime init`. In order
to run it with built-in templates you have to set the path to the config
file:
```
export SPACETIMEDB_CLI_TEMPLATES_FILE=crates/cli/.init-templates.json
```
In the future it will fetch the list from GH.
A few notes:
* the previous functionality of `spacetime init` does not work at the
moment
* the code needs a bit more cleanup and tests before merging
* there is a bit of a mix in how we generate empty server and client
projects. For Rust we use the existing way of generating. For TypeScript
we clone an empty project from the repo. I wanted to play with both ways
of doing things, and I'm still not sure which is better. Generation in
Rust means that the generated code will match the CLI version and not
necessarily whatever is in Git. On the other hand, for the builtin
templates we will be fetching the newest version from GH, which I guess
might also not what we want, ie. we probably want only stable templates.
More discussion is needed here
* we use `spacetimedb` directory for the server files
* I don't particularly like the inability to disable interactive mode
easily. We discussed disabling it by default if all of the required
arguments are passed, but I don't think it's feature proof. For example,
if someone relies on a non-interactive mode, and we add a new required
argument, instead of printing a message `missing --foo`, we will
automatically launch interactive mode, which is harder to debug. That's
why I think I'd prefer to implement `--non-interactive` argument
* it's kind of hard to keep the legacy behaviour. If you don't pass any
arguments, we go into interactive mode. In the legacy version, we would
print required arguments. If someone passes `--lang` or `--project-path`
explicitly, I guess we could run the legacy workflow, but not sure if
it's worth it, as the command was marked as unstable anyway
* the project path defaults to the project name, but I think we should
probably replace change whitespaces to dashes, or at least ask for the
project path with the project name being the default (or both)
---------
Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@aol.com>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
## Description of Changes
- Migrate the documentation site to **Docusaurus**.
- Add a **GitHub Action workflow** that runs `pnpm build` on pull
requests targeting `master`.
This command checks for broken links and images and ensures the site
builds correctly.
- Add a **GitHub Action workflow** to publish the docs automatically
when a merge occurs on the `docs/release` branch.
**Important**: The workflows haven't been tested yet due to the fact
that they need to be merged first before being able to run. It's a
fairly basic workflow I don't expect this to block anyone but anyways I
will make another PR with the complete changes when I can actually run
it.
---
## API and ABI Breaking Changes
No breaking changes for **SpacetimeDB** users.
Documentation contributors should experience minimal disruption —
content is still written in Markdown.
---
## Expected Complexity Level and Risk
**Complexity:** 3/5
**Reasons:**
1. Several adjustments were made to fit Docusaurus conventions:
- Replaced our custom `:::server-rust` blocks with [Docusaurus `<Tabs/>`
components](https://docusaurus.io/docs/markdown-features/tabs).
- Converted “Note” callouts using
[admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
instead of Markdown blockquotes.
- Updated all images (including Unity tutorial ones, which were
previously commented out).
- Moved images from the DO bucket into the repository at
`docs/static/images`.
2. Customized Docusaurus CSS and one component to apply our theme and
color palette.
---
## Testing
Tested locally.
---
## Review Notes
This PR involves many file changes — a full code review is likely not
productive.
Instead, please focus on verifying that the **documentation content**
was migrated correctly:
- Review sections you’re familiar with to confirm accuracy.
- Ensure formatting, links, and images render as expected.
You can follow the updated **README** for instructions on running
Docusaurus locally.
---------
Signed-off-by: Julien Lavocat <JulienLavocat@users.noreply.github.com>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Co-authored-by: = <cloutiertyler@gmail.com>
# Description of Changes
The quickstart smoketest was not correctly fudging our NuGet
dependencies to use the local versions of the packages, so it was
pulling them from NuGet. This ended up causing issues when we tried to
modify local packages and then use them in a way that affected the
quickstart (e.g.
https://github.com/clockworklabs/SpacetimeDB/pull/3386).
We had a few issues: we weren't ensuring that the local packages were
built, we weren't using the right directory for those packages, and we
weren't adding a "package source mapping" that forced those packages to
be used from the local directory.
# API and ABI breaking changes
None. CI-only.
# Expected complexity level and risk
2
# Testing
- [x] CI passes when
https://github.com/clockworklabs/SpacetimeDB/pull/3386 is merged
together with this PR (it wasn't before).
---------
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Finish the work started in #3227, which switched a hardcoded `127.0.0.1`
to a dynamic server address.
# API and ABI breaking changes
None.
# Expected complexity level and risk
1
# Testing
- [x] Smoketests still pass
- [ ] `Internal Tests` pass under this PR (they don't on master)
---------
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>
# Description of Changes
Closes
https://github.com/clockworklabs/SpacetimeDBPrivate/issues/1998#event-19488677475
Now the smoke test parse the `config.toml` for the correct address for
connecting.
# API and ABI breaking changes
<!-- If this is an API or ABI breaking change, please apply the
corresponding GitHub label. -->
# Expected complexity level and risk
1
# Testing
- [x] Run the smoke both on public / private
# Description of Changes
Closes#2100
Replay the `quickstart-chat` guide steps for the `Rust/C#` client &
server, and confirm the connection and `set_name`, `send_message`
commands.
# Expected complexity level and risk
1
# Testing
- [x] Added a smoke test
John Detter