diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index de15960e..c20d8770 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -7,17 +7,14 @@ jobs: runs-on: ubuntu-20.04 steps: - uses: actions/checkout@v2 - - uses: dart-lang/setup-dart@v1 - with: - sdk: beta + - uses: dart-lang/setup-dart@v1.3 - # Temporarily using a custom dartdoc until https://github.com/dart-lang/dartdoc/issues/2755 is fixed - name: Get dependencies run: dart pub get working-directory: docs - name: Run build env: - IS_RELEASE: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/master' }} + IS_RELEASE: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/latest-release' }} run: dart run tool/ci_build.dart working-directory: docs @@ -25,7 +22,7 @@ jobs: if: ${{ github.event_name == 'push' }} uses: nwtgck/actions-netlify@v1.2 with: - production-branch: master + production-branch: latest-release publish-dir: docs/deploy enable-pull-request-comment: true enable-commit-comment: false @@ -43,7 +40,7 @@ jobs: if: ${{ github.event_name == 'pull_request' }} uses: nwtgck/actions-netlify@v1.2 with: - production-branch: master + production-branch: latest-release publish-dir: docs/deploy enable-pull-request-comment: true enable-commit-comment: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d5db8035..ccdc8af3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,9 @@ # Contributing -Thanks for taking the time to contribute to moor! +Thanks for taking the time to contribute to drift! ## Reporting issues + Feel free to post any questions, bug reports or feature requests by creating an issue. In any case, taking the time to provide some context on - what you were trying to do @@ -15,27 +16,28 @@ most certainly helps to resolve the issue quickly. All kinds of pull requests are absolutely appreciated! Before working on bigger changes, it can be helpful to create an issue describing your plans to help coordination. -When working on moor, its recommended to fork the `develop` branch and also target that -branch for PRs. When possible, we only use the `master` branch to reflect the state that's -been released to pub. +When working on drift, its recommended to fork the `develop` branch and also target that +branch for PRs. When possible, we only use the `latest_release` branch to reflect the state +that's been released to pub. -If you have any question about moor internals that you feel are not explained well enough, +If you have any question about drift internals that you feel are not explained well enough, you're most welcome to create an issue or [chat via gitter](https://gitter.im/moor-dart/community). ## Project structure The project is divided into multiple modules: -- `moor/`: Contains common APIs that will run on all platforms. +- `drift/`: Contains common APIs that will run on all platforms. - `backends`: Common helper classes to make implementing backends easier. The idea is that a backend only needs to know how to run prepared statements. This lets us port the library to different database libraries without much trouble. - - `moor_web`: Experimental web implementation, built with `sql.js`. - - This is the biggest module, see the concepts section below on how moor works and what it + - `web.dart`: Experimental web implementation, built with `sql.js`. + - `native.dart`: FFI-based implementation around the `sqlite3` package. + - This is the biggest package, see the concepts section below on how drift works and what it contains. - `moor_flutter/`: Contains a Flutter implementation for the database. -- `moor_generator/`: Creates table, database and dao classes from the table structure and +- `drift_dev/`: Creates table, database and dao classes from the table structure and compiled queries. -- `sqlparser/`: Contains an sql parser and analyzer that is fairly independent of moor, +- `sqlparser/`: Contains an sql parser and analyzer that is mostly independent of drift, but used by the generator for compiled custom queries. ## Concepts @@ -49,7 +51,7 @@ we generate three classes: 3. A class to represent partial data (e.g. for inserts or updates, where not all columns are set). This class was introduced in moor 1.5 and is called a "companion". -This approach lets us write a higher-level api that uses the generated `TableInfo` classes to know what columns to +This approach lets us write a higher-level api that uses the generated `TableInfo` classes to know what columns to write. For instance, the `Migrator` can write `CREATE TABLE` statements from these classes, an `UpdateStatement` will write `UPDATE` statements and so on. To write the query, we construct a `GenerationContext`, which contains a string buffer to write the query, keeps track of the introduced variables and so on. The idea is that everything that can @@ -60,8 +62,8 @@ This query is then sent to a `QueryExecutor`, which is responsible for executing restricted libraries. ### Important classes -A `DatabaseConnectionUser` is the central piece of a moor database instance. It contains an `SqlTypeSystem` (responsible -for mapping simple Dart objects from and to sql), the `QueryExecutor` discussed above and a `StreamQueryStore` +A `DatabaseConnectionUser` is the central piece of a drift database instance. It contains an `SqlTypeSystem` (responsible +for mapping simple Dart objects from and to sql), the `QueryExecutor` discussed above and a `StreamQueryStore` (responsible for keeping active queries and re-running them when a table updates). It is also the super class of `GeneratedDatabase` and `DatabaseAccessor`, which are the classes a `@UseMoor` and `@UseDao` class inherits from. Finally, the `QueryEngine` is a mixin in `DatabaseConnectionUser` that provides the `select`, `update`, `delete` methods @@ -80,8 +82,8 @@ Note: Port 9999 has to be free for this to work, but you can change the port defined in the two files below. To debug the plugin, do the following: -1. In `moor/tools/analyzer_plugin/bin/plugin.dart`, set `useDebuggingVariant` to true. -2. Run `moor_generator/bin/moor_generator.dart debug-plugin` as a regular Dart VM app +1. In `drift/tools/analyzer_plugin/bin/plugin.dart`, set `useDebuggingVariant` to true. +2. Run `drift_dev/tool/debug_plugin.dart` as a regular Dart VM app (this can be debugged when started from an IDE). 3. (optional) Make sure the analysis server picks up the updated version of the analysis plugin by deleting the `~/.dartServer/.plugin_manager` folder. @@ -91,7 +93,7 @@ More details are available under `extras/plugin_example/README.md`. ### Debugging the builder -To debug the builder, run `pub run build_runner generate-build-script` in the `moor` +To debug the builder, run `pub run build_runner generate-build-script` in the `drift` subdirectory (or any other directory you want to use as an input). This will generate a `.dart_tool/build/entrypoint/build.dart`. That file can be run and debugged as a regular Dart VM app. Be sure to pass something like `build -v` as program arguments @@ -101,26 +103,25 @@ and use the input package as a working directory. Minor changes will be published directly, no special steps are necessary. For major updates that span multiple versions, we should follow these steps -1. Changelogs: For new updates, we use the same `CHANGELOG` for `moor` and `moor_flutter`. This - is because most changes happen with moor directly, but users are most likely depending on the - Flutter version only. The changelog for the generator should only point out relevant changes to - the generator. -2. Make sure each package has the correct dependencies: `moor_flutter` version `1.x` should depend - on moor `1.x` as well to ensure users will always `pub get` moor packages that are compatible +1. Changelogs: The changelog of `drift_dev` should only mention changes to the generator, + most changes shuold be in `drift/CHANGELOG.md`. Generator changes should also be copied + into that file. +2. Make sure each package has the correct dependencies: `drift_dev` version `1.x` should depend + on `drift` `1.x` as well to ensure users will always `pub get` drift packages that are compatible with each other. -3. Comment out the `dependency_overrides` section in `moor`, `moor/tool/analyzer_plugin`, `moor_flutter`, - `moor_generator` and `sqlparser`. Make sure that `useDebuggingVariant` is false in the +3. Comment out the `dependency_overrides` section in `drift`, `drift/tool/analyzer_plugin`, `moor_flutter`, + `drift_dev` and `sqlparser`. Make sure that `useDebuggingVariant` is false in the analyzer plugin. -4. Publish packages in this order to avoid scoring penalties caused by versions not existing: - 1. `moor` - 2. `moor_generator` - 3. `moor_flutter` - -The `sqlparser` library can be published independently from moor. +4. Create an annotated tag and a GitHub release for each package published. `drift` and `drift_dev` can be + merged into a single GitHub release. +5. Publish packages in this order to avoid scoring penalties caused by versions not existing: + 1. `drift` + 2. `drift_dev` + 3. (optional) `moor_flutter` -Significant updates to more than one package, or updates to the `moor` package, should get -their own tag in git! +The `sqlparser` library can be published independently from drift. ### Building the documentation -We use hugo and docsy to build the documentation. The [readme](docs/README.md) contains everything -you need to know go get started. \ No newline at end of file + +We use `build_runner` to build the documentation. The [readme](docs/README.md) contains everything +you need to know go get started. diff --git a/docs/lib/_style.scss b/docs/lib/_style.scss index 43341826..0335d376 100644 --- a/docs/lib/_style.scss +++ b/docs/lib/_style.scss @@ -1,6 +1,8 @@ @import 'variables.scss'; @import '_highlight.scss'; +$enable-rounded: true; + .renamed { padding: 10px; background-color: rgba(0, 0, 0, 0.08); diff --git a/docs/pages/docs/Advanced Features/migrations.md b/docs/pages/docs/Advanced Features/migrations.md index 900bf74f..75bffd23 100644 --- a/docs/pages/docs/Advanced Features/migrations.md +++ b/docs/pages/docs/Advanced Features/migrations.md @@ -246,7 +246,7 @@ By using those test databases, drift can help you test migrations from and to an {% block "blocks/alert" title="Complex topic ahead" %} > Writing schema tests is an advanced topic that requires a fairly complex setup described here. If you get stuck along the way, don't hesitate to [open a discussion about it](https://github.com/simolus3/moor/discussions). - Also, there's a working example [in the drift repository](https://github.com/simolus3/moor/tree/master/extras/migrations_example). + Also, there's a working example [in the drift repository](https://github.com/simolus3/moor/tree/latest-release/extras/migrations_example). {% endblock %} ### Setup diff --git a/docs/pages/docs/platforms.md b/docs/pages/docs/platforms.md index 515220c2..2ec48fdd 100644 --- a/docs/pages/docs/platforms.md +++ b/docs/pages/docs/platforms.md @@ -38,7 +38,7 @@ package when using `package:drift/native.dart`! {% block "blocks/alert" title="A note on ffi and Android" %} > `package:drift/native.dart` is the recommended drift implementation for new Android apps. However, there are some smaller issues on some devices that you should be aware of: - + - Using `sqlite3_flutter_libs` will include prebuilt binaries for 32-bit `x86` devices which you probably won't need. You can apply a [filter](https://github.com/simolus3/sqlite3.dart/tree/master/sqlite3_flutter_libs#included-platforms) in your `build.gradle` to remove those binaries. diff --git a/docs/tool/ci_build.dart b/docs/tool/ci_build.dart index c38157c8..6ee3f4f5 100644 --- a/docs/tool/ci_build.dart +++ b/docs/tool/ci_build.dart @@ -80,8 +80,9 @@ Future _createApiDocumentation(Directory output) async { // the line number. const source = 'https://github.com/simolus3/moor/blob/%r%/%f%/#L%l%'; final dartDoc = await Process.start( - 'dartdoc', + 'dart', [ + 'doc', '--rel-canonical-prefix=https://pub.dev/documentation/drift/latest', '--link-to-source-revision=$rev', '--link-to-source-root=..', diff --git a/docs/website.yaml b/docs/website.yaml index cba44bef..1730ed0f 100644 --- a/docs/website.yaml +++ b/docs/website.yaml @@ -7,7 +7,7 @@ site: copyright: "Simon Binder" github_repo: "https://github.com/simolus3/moor" github_subdir: "docs/" - github_branch: master + github_branch: latest-release gcs_engine_id: set # this just needs to be set so that the search box shows sidebar_search_disable: true