Skip to content

Commit f1d607c

Browse files
martinbonninBoD
martinbonnin
and
BoD
authored
[📚docs] Update docs for v4 (#6044)
* update badges * Rework the main page * add emojis * Use link instead of copying the logo everywhere * wording * Use external link for the KDoc * Update docs * move mulitplatform down * remove apollo-adapters mention * index.md * remove warning deprecations, only talk about actual breaking changes * nicer titles * Update galaxy * update migration guide * fix the apollo-adapters-kotlinx-datetime artifact id * Update docs/source/advanced/galaxy.mdx Co-authored-by: Benoit 'BoD' Lubek <[email protected]> * Update docs/source/migration/4.0.mdx Co-authored-by: Benoit 'BoD' Lubek <[email protected]> --------- Co-authored-by: Benoit 'BoD' Lubek <[email protected]>
1 parent 0cf7809 commit f1d607c

File tree

10 files changed

+110
-178
lines changed

10 files changed

+110
-178
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Apollo Kotlin executes operations against a GraphQL server and returns results a
2828

2929
Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.
3030

31-
This library is designed with Android in mind, but you can use it in any Kotlin application, including multiplatform.
31+
This library is designed with Android in mind, but you can use it in any Kotlin application, including KMP ([Kotlin Multi Platform](https://kotlinlang.org/docs/multiplatform.html)).
3232

3333
## 📚 Documentation
3434

‎docs/source/advanced/galaxy.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,17 @@ title: Apollo Kotlin galaxy
55

66
The Apollo Kotlin galaxy is a collection of projects that are related to Apollo Kotlin but are loosely coupled. Their release schedule and maturity level varies.
77

8-
They serve as playground for new ideas (apollo-kotlin-compose-support, apollo-kotlin-normalized-cache-incubating) or as helper projects providing additional functionality that is not ready to be included in the main repository or has external dependencies (apollo-kotlin-mockserver, apollo-kotlin-adapters).
8+
They serve as a playground for new ideas (`apollo-kotlin-compose-support`, `apollo-kotlin-normalized-cache-incubating`) or helper projects providing additional functionality that is not core to Apollo Kotlin (`apollo-kotlin-mockserver`, `apollo-kotlin-cli`, `apollo-kotlin-execution`)
99

1010
The Apollo Kotlin galaxy projects all start with `apollo-kotlin`:
1111

1212
| Repository | Description |
1313
|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
14-
| [apollo-kotlin-execution](https://github.com/apollographql/apollo-kotlin-execution) | GraphQL execution algorithms |
15-
| [apollo-kotlin-ktor-support](https://github.com/apollographql/apollo-kotlin-ktor-support) | HttpEngine and helpers to work with [Ktor](https://ktor.io/) |
16-
| [apollo-kotlin-adapters](https://github.com/apollographql/apollo-kotlin-adapters) | Datetime, BigDecimal and other adapters for Apollo Kotlin |
1714
| [apollo-kotlin-normalized-cache-incubating](https://github.com/apollographql/apollo-kotlin-normalized-cache-incubating) | Apollo Kotlin Incubating Normalized Cache |
1815
| [apollo-kotlin-compose-support](https://github.com/apollographql/apollo-kotlin-compose-support) | Compose support for Apollo Kotlin |
16+
| [apollo-kotlin-ktor-support](https://github.com/apollographql/apollo-kotlin-ktor-support) | HttpEngine and helpers to work with [Ktor](https://ktor.io/) |
17+
| [apollo-kotlin-execution](https://github.com/apollographql/apollo-kotlin-execution) | GraphQL execution algorithms |
18+
| [apollo-kotlin-adapters](https://github.com/apollographql/apollo-kotlin-adapters) | Datetime, BigDecimal and other adapters for Apollo Kotlin |
1919
| [apollo-kotlin-cli](https://github.com/apollographql/apollo-kotlin-cli) | Command line tool for your GraphQL projects |
2020
| [apollo-kotlin-mockserver](https://github.com/apollographql/apollo-kotlin-mockserver) | KMP ready HTTP mock server |
2121
| [apollo-kotlin-java-support](https://github.com/apollographql/apollo-java-support) | Java language support for Apollo Kotlin |

‎docs/source/config.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"Get Started": "/",
99
"Migrating to v4": "/migration/4.0",
1010
"Evolution policy": "/essentials/evolution",
11-
"Kdoc": "https://www.apollographql.com/docs/kotlin/kdoc/",
11+
"Kdoc": "https://apollographql.github.io/apollo-kotlin/kdoc/",
1212
"Changelog": "https://github.com/apollographql/apollo-kotlin/blob/main/CHANGELOG.md",
1313
"Tutorial": {
1414
"0. Introduction": "/tutorial/00-introduction",

‎docs/source/essentials/errors.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ if (response.data != null) {
1212
} else {
1313
// Something wrong happened
1414
if (response.exception != null) {
15-
// Handle non-GraphQL errors
15+
// Handle fetch errors
1616
} else {
1717
// Handle GraphQL errors in response.errors
1818
}
@@ -27,7 +27,7 @@ apolloClient.subscription(subscription).toFlow().collect { response ->
2727
// Handle (potentially partial) data
2828
} else {
2929
if (response.exception != null) {
30-
// Handle non-GraphQL errors
30+
// Handle fetch errors
3131
} else {
3232
// Handle GraphQL errors in response.errors
3333
}

‎docs/source/essentials/evolution.mdx

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -56,15 +56,17 @@ Other changes are dealt with on a case by case basis. When possible, we’ll hav
5656

5757
Whether something is a bugfix or another kind of change [is left to interpretation,](https://xkcd.com/1172/) and we’ll try our best to make reasonable choices there.
5858

59-
## `@ApolloExperimental`
59+
## Symbol lifecycle
60+
61+
### @ApolloExperimental
6062

6163
Symbols marked with `@ApolloExperimental` are not part of the public API and are therefore subject to change at any time.
6264

63-
## `@Deprecated`
65+
### @Deprecated
6466

65-
Deprecated symbols are removed when:
67+
Symbols marked with `@Deprecated` are removed when:
6668

67-
* A major version is released
69+
* A major version is released...
6870
* AND the symbol has been deprecated for at least 6 months.
6971

70-
Ideally (but we can’t guarantee it), we’ll try to provide a one year update window (6 months as warning, 6 months as error).
72+
Ideally (but we can't guarantee it), we’ll try to provide a one-year update window (6 months as warning, 6 months as error).

‎docs/source/index.md

Lines changed: 44 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,24 @@ title: Introduction to Apollo Kotlin
33
description: A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform.
44
---
55

6-
> 📣 **Apollo Kotlin 3 is generally available.** If you're using Apollo Android 2.x, see the [migration guide](./migration/3.0/). You can also [view the 2.x docs](https://www.apollographql.com/docs/kotlin/v2).
6+
> 📣 **Migration guide:** if you're using Apollo Kotlin 3, see the [migration guide](./migration/4.0/). You can also [view the 3.x docs](https://www.apollographql.com/docs/kotlin/v3).
77
8-
[Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) (formerly Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL operations.
8+
[Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) is a strongly typed GraphQL client that generates Kotlin models for your GraphQL operations.
99

1010
Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.
1111

1212
Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.
1313

14-
This library is designed primarily with Android in mind, but you can use it in any Kotlin (including multiplatform) and Java app.
14+
This library is designed with Android in mind, but you can use it in any Kotlin application, including KMP ([Kotlin Multi Platform](https://kotlinlang.org/docs/multiplatform.html)).
1515

1616
## Features
1717

18-
* Kotlin Multiplatform and Java code generation
18+
* Kotlin Multiplatform code generation
1919
* Queries, Mutations and Subscriptions
2020
* Reflection-free parsing
2121
* Normalized cache
22-
* Custom scalar types
2322
* HTTP cache
23+
* Custom scalar types
2424
* Auto Persisted Queries
2525
* Query batching
2626
* File uploads
@@ -29,40 +29,11 @@ This library is designed primarily with Android in mind, but you can use it in a
2929
* GraphQL AST parser
3030
* Plugin for Android Studio and IntelliJ
3131

32-
## Multiplatform
33-
34-
Apollo Kotlin is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project.
35-
36-
Here's the current matrix of supported features per platform:
37-
38-
| | `jvm` | `Apple¹` | `js` | `wasmJs` | `linuxX64` |
39-
|------------------------------------------------------|:-----:|:--------:|:----:|:--------:|:----------:|
40-
| `apollo-api` (models) | ✅ | ✅ | ✅ | ✅ | ✅ |
41-
| `apollo-runtime` (network, query batching, apq, ...) | ✅ | ✅ | ✅ | ✅ | 🚫 |
42-
| `apollo-normalized-cache` | ✅ | ✅ | ✅ | ✅ | 🚫 |
43-
| `apollo-adapters` | ✅ | ✅ | ✅ | ✅ | 🚫 |
44-
| `apollo-normalized-cache-sqlite` | ✅ | ✅ | 🚫 | 🚫 | 🚫 |
45-
| `apollo-http-cache` | ✅ | 🚫 | 🚫 | 🚫 | 🚫 |
46-
47-
¹: Apple currently includes:
48-
49-
- `macosX64`
50-
- `macosArm64`
51-
- `iosArm64`
52-
- `iosX64`
53-
- `iosSimulatorArm64`
54-
- `watchosArm32`
55-
- `watchosArm64`
56-
- `watchosSimulatorArm64`
57-
- `tvosArm64`
58-
- `tvosX64`
59-
- `tvosSimulatorArm64`
60-
6132
## Getting started
6233

6334
If you are new to GraphQL, check out [the tutorial](./tutorial/00-introduction/) that will guide you through building an Android app using Apollo.
6435

65-
If you'd like to add Apollo Kotlin to an existing project, follow these steps:
36+
If you'd like to add Apollo Kotlin to an existing project, follow the steps below.
6637

6738
Add the plugin to your `build.gradle.kts`:
6839

@@ -95,7 +66,7 @@ Apollo Kotlin supports three types of files:
9566
- `.json` schema files: describes the types in your backend using the Json syntax.
9667
- `.graphql` executable files: describes your queries and operations in the GraphQL syntax.
9768

98-
By default, Apollo Kotlin requires a schema in your module's `src/main/graphql` directory. You can download a schema using introspection with the `./gradlew downloadApolloSchema` task. Sometimes introspection is disabled and you will have to ask your backend team to provide a schema. Copy this schema to your module:
69+
By default, Apollo Kotlin requires a schema in your module's `src/main/graphql` (or `src/commonMain/graphql` for KMP) directory. You can download a schema using introspection with the `./gradlew downloadApolloSchema` task. Sometimes introspection is disabled, and you will have to ask your backend team to provide a schema. Copy this schema to your module:
9970

10071
```
10172
cp ${schema} ${module}/src/main/graphql/
@@ -113,7 +84,7 @@ query HeroQuery($id: String!) {
11384
}
11485
```
11586

116-
Build your project. This will generate a `HeroQuery` class that you can use with an instance of `ApolloClient`:
87+
Build your project. This generates a `HeroQuery` class that you can use with an instance of `ApolloClient`:
11788

11889
```kotlin
11990
// Create a client
@@ -129,16 +100,45 @@ Build your project. This will generate a `HeroQuery` class that you can use with
129100

130101
**To learn more about other Apollo Kotlin APIs:**
131102

132-
* Execute your first [mutation](./essentials/mutations/)
133-
* Handle [custom scalar types](./essentials/custom-scalars/)
134-
* Factor common patterns using [fragments](./essentials/fragments/)
103+
* Execute your first [mutation](./essentials/mutations/).
104+
* Handle [custom scalar types](./essentials/custom-scalars/).
105+
* Factor common patterns using [fragments](./essentials/fragments/).
106+
107+
## Multiplatform
108+
109+
Apollo Kotlin is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project.
110+
111+
Here's the current matrix of supported features per platform:
112+
113+
| | `jvm` | `Apple¹` | `js` | `wasmJs` | `linuxX64` |
114+
|------------------------------------------------------|:-----:|:--------:|:----:|:--------:|:----------:|
115+
| `apollo-api` (models) | ✅ | ✅ | ✅ | ✅ | ✅ |
116+
| `apollo-runtime` (network, query batching, apq, ...) | ✅ | ✅ | ✅ | ✅ | 🚫 |
117+
| `apollo-normalized-cache` | ✅ | ✅ | ✅ | ✅ | 🚫 |
118+
| `apollo-adapters` | ✅ | ✅ | ✅ | ✅ | 🚫 |
119+
| `apollo-normalized-cache-sqlite` | ✅ | ✅ | 🚫 | 🚫 | 🚫 |
120+
| `apollo-http-cache` | ✅ | 🚫 | 🚫 | 🚫 | 🚫 |
121+
122+
¹: Apple currently includes:
123+
124+
- `macosX64`
125+
- `macosArm64`
126+
- `iosArm64`
127+
- `iosX64`
128+
- `iosSimulatorArm64`
129+
- `watchosArm32`
130+
- `watchosArm64`
131+
- `watchosSimulatorArm64`
132+
- `tvosArm64`
133+
- `tvosX64`
134+
- `tvosSimulatorArm64`
135135

136136
## Requirements
137137

138138
Some platforms have specific runtime requirements:
139139

140140
* JVM 8+
141-
* Android API level 21+ (`apollo-http-cache` and `apollo-adapters` require enabling [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) on Android API levels < 26)
141+
* Android API level 21+ (`apollo-http-cache` requires enabling [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) on Android API levels < 26)
142142
* iOS 13+
143143

144144
At build time, it requires:
@@ -159,7 +159,7 @@ Installation instructions and more information can be found [here](testing/andro
159159

160160
## Releases
161161

162-
The latest version is [![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.apollo/apollo-api)](https://repo1.maven.org/maven2/com/apollographql/apollo/)
162+
The latest version is `4.0.0-rc.1`.
163163

164164
Check the [changelog](https://github.com/apollographql/apollo-kotlin/releases) for the release history.
165165

@@ -218,14 +218,9 @@ These snapshots are updated on each push to `main`.
218218

219219
Weekly snapshots for the Android Studio / IntelliJ plugin [are also available](testing/android-studio-plugin#weekly-snapshots).
220220

221-
## Stability of different artifacts
222-
223-
Apollo Kotlin is very modular and publishes several artifacts.
221+
## Evolution policy
224222

225-
* Artifacts ending with `-incubating` are not finalized yet and subject to change any time.
226-
* Other artifacts observe [Semantic Versioning](https://semver.org/).
227-
* No breaking change should be introduced in minor or patch releases except for symbols annotated with `@ApolloExperimental` that are subject to change at any time.
228-
* Deprecated symbols may be removed in the next major release. We strongly recommend removing deprecated usages before migrating to the next major version.
223+
You can read about our evolution policy in the [dedicated page](essentials/evolution)
229224

230225
## Contributing
231226

0 commit comments

Comments
 (0)