Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add important callout in README for colima users #458

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add important callout in README for colima users #458

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 54 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,17 +44,17 @@ OpenFGA is designed to make it easy for application builders to model their perm
## Currently Supported SDKs

| Language | GitHub | Package Manager |
|------------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Javascript | [openfga/js-sdk](https://github.com/openfga/js-sdk) | [![@openfga/sdk on npm](https://img.shields.io/npm/v/@openfga/sdk.svg?label=@openfga/sdk&style=flat-square)](https://www.npmjs.com/package/@openfga/sdk) |
| Go | [openfga/go-sdk](https://github.com/openfga/go-sdk) | [![OpenFGA Go SDK on GitHub](https://img.shields.io/github/v/release/openfga/go-sdk?label=openfga-go-sdk&style=flat-square)](https://github.com/openfga/go-sdk) |
| .NET | [openfga/dotnet-sdk](https://github.com/openfga/dotnet-sdk) | [![OpenFga.Sdk on NuGet](https://img.shields.io/nuget/v/OpenFga.Sdk?label=OpenFga.Sdk&style=flat-square)](https://www.nuget.org/packages/OpenFga.Sdk) |
| Python | [openfga/python-sdk](https://github.com/openfga/python-sdk) | [![openfga-sdk on PyPi](https://img.shields.io/pypi/v/openfga_sdk.svg?label=openfga-sdk&style=flat-square)](https://pypi.org/project/openfga_sdk) |
| Java | [openfga/java-sdk](https://github.com/openfga/java-sdk) | [![openfga-sdk on Maven Central](https://img.shields.io/maven-central/v/dev.openfga/openfga-sdk?style=flat-square&label=openfga-sdk)](https://central.sonatype.com/artifact/dev.openfga/openfga-sdk) |


## Getting Started

### Requirements

1. Git
2. Docker
3. Make (Optional, but makes things much easier)
Expand All @@ -81,13 +81,15 @@ git clone [email protected]:openfga/java-sdk.git clients/fga-java-sdk
```

3. Build and test the client sdks

```shell
make
```

### Adding a new SDK

#### Using the setup script

There is a helpful script to setup a new SDK

```shell
Expand All @@ -99,48 +101,58 @@ make setup-new-sdk
3. Then in will initialize all the files, you will need to add the configuration specific to that sdk
4. Now you can run `make build-client-${SDK_ID}` to generate the SDK

> [!IMPORTANT]
> If using Colima to run docker, you must add `$TMPDIR` as a location in the `mounts` section of the [colima.yaml](https://github.com/abiosoft/colima/blob/main/embedded/defaults/colima.yaml#L185-L198) for `make build-client-${SDK_ID}` to succeed. Otherwise, the build script cannot mount the directory where the required `config.json` is created and the command will fail.

#### Manually

1. Create config dir in: `config/clients/{lang}/`. It should include:
* `CHANGELOG.md`: To be updated as new releases are generated
* `generator.txt`: the name of the generator to use. Must be a [valid generator](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators.md)
* `config.overrides.json`: Custom config for this generator + overrides to the common config in `config/common/config.base.json`
* `.openapi-generator-ignore`: Any files that the generator should ignore and not built
* `template-source`: Newer SDKs should have this to mark what commit of the generator we branched off
* `template/` directory
* `LICENSE`: Apache-2.0 License
* `.github/workflows/main.yml`: Any CI checks that need to run
* The following files, each with the relevant section (look at the JS template for an example):
* `README_installation.mustache`
* `README_initializing.mustache`
* `README_calling_api.mustache`
* `README_api_endpoints.mustache`
* `README_models.mustache`
* `README_license_disclaimer.mustache`
* `README_custom_badges.mustache` (optional, any custom badges for this specific SDK)
* `gitignore_custom.mustache` (optional, any custom ignores for this specific SDK)
* `NOTICE_details.mustache` (optional, see [Updating the Notice files](#updating-the-notice-files))
* custom files according to the generator
- `CHANGELOG.md`: To be updated as new releases are generated
- `generator.txt`: the name of the generator to use. Must be a [valid generator](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators.md)
- `config.overrides.json`: Custom config for this generator + overrides to the common config in `config/common/config.base.json`
- `.openapi-generator-ignore`: Any files that the generator should ignore and not built
- `template-source`: Newer SDKs should have this to mark what commit of the generator we branched off
- `template/` directory
- `LICENSE`: Apache-2.0 License
- `.github/workflows/main.yml`: Any CI checks that need to run
- The following files, each with the relevant section (look at the JS template for an example):
- `README_installation.mustache`
- `README_initializing.mustache`
- `README_calling_api.mustache`
- `README_api_endpoints.mustache`
- `README_models.mustache`
- `README_license_disclaimer.mustache`
- `README_custom_badges.mustache` (optional, any custom badges for this specific SDK)
- `gitignore_custom.mustache` (optional, any custom ignores for this specific SDK)
- `NOTICE_details.mustache` (optional, see [Updating the Notice files](#updating-the-notice-files))
- custom files according to the generator
2. Update the `Makefile`.
1. add a target for the new sdk

```makefile
.PHONY: build-client-{{LANG}}
build-client-{{LANG}}:
make build-client sdk_language={{LANG}} tmpdir=${TMP_DIR}
# ... any other custom build steps ...
```
2. add it as a dependency to the `build-all-clients`

2. add it as a dependency to the `build-all-clients`

```makefile
.PHONY: build-all-clients
build-all-clients: build-client-js build-client-go ... build-client-{{LANG}}
```
3. add a target for the new sdk's tests that depend on the build target

3. add a target for the new sdk's tests that depend on the build target

```makefile
.PHONY: test-client-{{LANG}}
test-client-{{LANG}}: build-client-{{LANG}}
# ... any custom test code ...
```
4. add it as a dependency to the `test-all-clients`

4. add it as a dependency to the `test-all-clients`

```makefile
.PHONY: test-all-clients
test-all-clients: test-client-js test-client-go ... test-client-{{LANG}}
Expand All @@ -149,19 +161,22 @@ test-all-clients: test-client-js test-client-go ... test-client-{{LANG}}
> Note: Try to ensure that the SDK is built through container files so that other contributors would not need to set up the full language framework/toolchain whenever they need to contribute. Checkout the [go sdk build steps](https://github.com/openfga/sdk-generator/blob/bf6709a5faba14ce260f4f8df019dddd54078df0/Makefile#L76) as an example.

### Updating the Notice files

1- Ensure that `fossaComplianceNoticeId` has been set in each SDK's config overrides.
2- Run `make update-fossa-reports`

### Uploading the SDK

Once the SDK is ready, you need to:
* Create a repo under the [openfga](https://github.com/openfga) github org. Call it: `${SDK_ID}-sdk`
* Add it to the generator's test and deploy actions
* Add any necessary secrets to the generator's repo on github (and document them in the readme)

- Create a repo under the [openfga](https://github.com/openfga) github org. Call it: `${SDK_ID}-sdk`
- Add it to the generator's test and deploy actions
- Add any necessary secrets to the generator's repo on github (and document them in the readme)

### Publishing/Open Sourcing the SDK

Once the SDK is ready, you need to:

1. Setup Snyk, and ensure no security issues are present
2. Setup Fossa, and ensure no compliance issues are present
3. Request a review from the team
Expand All @@ -170,29 +185,30 @@ Note: Semgrep will be automatically enabled - there is nothing you need to do fo

### GitHub Action Secrets

| Key | Comment |
|-----------------------------|-----------------------------------------------------------------------------|
| `FOSSA_API_KEY` | FOSSA API Key |
| `SNYK_TOKEN` | Snyk API Key |
| Key | Comment |
| --------------- | ------------- |
| `FOSSA_API_KEY` | FOSSA API Key |
| `SNYK_TOKEN` | Snyk API Key |

## Contributing

Please review the [Contributing Guidelines](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md) before sending a PR or opening an issue.

In addition, we ask that the SDKs:

* be generated from the [openapiv2 swagger document](https://github.com/openfga/api/blob/main/docs/openapiv2/apidocs.swagger.json) using the sdk-generator.
- be generated from the [openapiv2 swagger document](https://github.com/openfga/api/blob/main/docs/openapiv2/apidocs.swagger.json) using the sdk-generator.

* have roughly the same consistent interface for configuration, such as [JS](https://github.com/openfga/js-sdk), [GoLang](https://github.com/openfga/go-sdk), [.NET](https://github.com/openfga/dotnet-sdk), [Python](https://github.com/openfga/python-sdk) and [Java](https://github.com/openfga/java-sdk) SDKs.
- have roughly the same consistent interface for configuration, such as [JS](https://github.com/openfga/js-sdk), [GoLang](https://github.com/openfga/go-sdk), [.NET](https://github.com/openfga/dotnet-sdk), [Python](https://github.com/openfga/python-sdk) and [Java](https://github.com/openfga/java-sdk) SDKs.

* support the same features with other existing SDKs, including: Retries, Error Handling, .
- support the same features with other existing SDKs, including: Retries, Error Handling, .

* have a base set of functional tests.
- have a base set of functional tests.

* have no tests that talk to an external service (external calls should be disallowed and mocked).
- have no tests that talk to an external service (external calls should be disallowed and mocked).

* have building & publishing automated through GitHub actions.
- have building & publishing automated through GitHub actions.

* be created and modified through pull requests to this sdk-generator repository instead of individual repositories. Most of the code will be in mustache files that will end up generating the resulting SDK for the appropriate language.
- be created and modified through pull requests to this sdk-generator repository instead of individual repositories. Most of the code will be in mustache files that will end up generating the resulting SDK for the appropriate language.

## Author

Expand Down
Loading