Is Developing SDKs Currently Convenient? #455
Description
Important
There is no clear-cut answer to this question. However, I’d like to share my perspective. I understand that the current approach to developing various SDKs is deeply embedded in the workflow, making it difficult to change.
Nevertheless, I see some downsides in the process that hinder a developer-friendly experience.
Of course, I invite discussion and constructive feedback.
Context
How do I currently develop the Java SDK?
I have the sdk-generator repository checked out. Additionally, I have the java-sdk repository checked out. To add or refactor anything, I develop directly in the java-sdk project. This allows me to take full advantage of IDE features (test running, refactoring tools, code completion, etc.).
Once I’m satisfied with my changes, I manually transfer them to sdk-generator. Not very convenient, huh?
Challenges
mustache files
The nature of mustache files makes them difficult to edit, format, or refactor in the context of the language in which the SDK is developed.
Additionally, a lack of familiarity with OpenAPI Generator may discourage developers from making changes.
Different States Between Specific SDKs and the Generator
A problematic scenario arises when someone modifies, for example, the java-sdk but does not transfer these changes to sdk-generator. Other developers working on SDKs then face discrepancies between the java-sdk and sdk-generator. In such cases, the first step is often to align the state of sdk-generator with the specific SDK. However, aligning someone else's changes could be challenging.
Different SDK Lifecycles
Various SDKs have different lifecycles and development paces, which suggests distinct release cycles. This is why they should be maintained in separate repositories, allowing for proper versioning. Otherwise, the development of new SDKs may be slowed down.
For instance, @evansims prepared an excellent PoC for php-sdk. If we had separate repositories, the new SDK could be released as unstable (alpha, beta) without impacting stable SDKs. This would allow for a broader adoption process for new users.
Solutions
Generate Model
One of the most useful features of sdk-generator is generating models from OpenAPI specifications and the OpenFgaApi class — although even that is highly customized.
Other classes, such as utils, configurations, tests, and API clients, are unrelated to the OpenAPI specification. Since they are mustache templates, maintaining them is inconvenient.
Common Files
Many shared files can be managed using GitHub’s built-in mechanisms, such as shared workflows or templates for issues and pull requests.
Project Management
Currently, issues in sdk-generator serve as a hub for feature requests and bug reports, and they are added to the SDKs and Tooling project.
If SDK repositories were separate, then issues in sdk-generator could still act as a hub for all SDKs. An alternative approach would be to use sdk-generator as a hub for larger initiatives (epics) that should be applied across all SDKs. Using sub-issues, we could link individual tasks for each SDK. Specific bugs for a given SDK would be reported in their respective repositories and linked to the SDKs and Tooling project.
If I missed anything, let me know. I'm very curious to hear the OpenFGA team's opinion on this process. As I mentioned, I'm open to further discussion and eager to address any gaps in the process.