Our Move to Generated SDKs

[nickfloyd]

Taking a Leap: Introducing Our Generated Go and .NET SDKs

We are excited to announce a significant shift in our approach to software development kits (SDKs) at GitHub. Moving away from the static landscape of the traditional Octokit, we are now alpha shipping two newly generated SDKs using Kiota; one published in Go and the other in .NET. This marks a pivotal moment in our journey towards more dynamic, flexible, and user-friendly tools for our community.

ℹ️ Note: This does not mean we are bring anything to an end of life status just yet. There are millions of implementations/dependents on Octokit js/rb/.net/.etc and we are still working on and supporting those SDKs. This effort is meant to bring us all together to build the next iteration of Octokit.

Why Move Away from our traditional Octokit SDKs?

Octokit has been an integral part of GitHub's ecosystem, offering a robust interface for interacting with GitHub's APIs. However, as technology evolves, so should our tools. The new SDKs are not just about generating code; they are about ushering in a new era of building and integrating with GitHub. By leveraging this generative approach we will be able to provide near instant updates to models and API while also moving into new areas such as SDK workflows that act as a single point to holistically address more complex use cases.

Why Kiota?

We tried dozens of generative approaches, even writing our own, but one framework, Kiota, written by our friends at Microsoft, always bubbled to the top. Kiota is a command line tool that takes OpenAPI definitions and creates clean SDKs based on those definitions. This enables generation of well structured clients for a given API while allowing hand curation of the more esoteric needs of the SDK users.

Choosing Kiota as our generation engine aligns with our goal to embrace modern, efficient, and versatile technology. Kiota's ability to generate comprehensive, idiomatic SDKs from GitHub's OpenAPI specification perfectly complements our vision for the future of GitHub integration, ensuring that our tools are not only powerful but also intuitive and developer-friendly.

The progress that has been made so far would not be possible without the amazing Kiota team and all of the help they have given our Octokit community.

First things: The Power of Go and .NET SDKs

The introduction of the Go and .NET SDKs represent our commitment to a broader and more diverse developer community. Go, known for its efficiency and scalability, and .NET, recognized for its versatility in various applications, are perfect candidates for the next generation of GitHub SDKs.

Not Just Code Generation - A Vision for the Future

We believe that the true value of these SDKs lies not in the code they generate but in the possibilities they unlock. While the models that are generated are important and having near 100% REST API coverage will remove usability roadblocks, those accomplishments were never the endgame.

Our goal is to build SDKs that get the software out of the way of the developer so that we can all focus on user needs. By generating what’s known, we will focus on the more interesting question of what’s needed next.

These tools are a gateway to a new era of innovation and creativity with GitHub. The intent is to build SDKs that are designed to empower developers to build more robust, efficient, and creative solutions on top of the GitHub platform.

Join Us in Shaping the Future

As we alpha ship these SDKs, we want and need you as the community to join us in this exciting journey. Your feedback, contributions, and insights are invaluable in shaping the future of GitHub integration.

This is not just a transition; it's a transformation. A transformation towards a more inclusive, dynamic, and innovative future with GitHub. Let's build this future together.

Stay tuned for more updates, and please reach out with your thoughts and contributions. Welcome to a new chapter in Octokit's story!

Your GitHub SDK team ♥️

❓ We have a short (1 page, 5-question) survey here we would love for people to take! Your perspective helps us decide what to prioritize next.

[kfcampbell]

❓ I've updated the post above with our very short survey. If you get a moment, please help us decide what to prioritize next!

[mungojam]

Sounds like a good approach. Is there an implied change of focus from the graphql back to the rest API? I'd wondered the same when a new feature was added to rest API but not graphql.

I'm pretty happy with either as long as the SDK is simple to use

[kfcampbell]

GitHub still has a mix of REST and GraphQL APIs, and this release does not affect what teams are choosing to build for. I expect both REST and GraphQL to remain in use at GitHub in the future; this does not imply a change of focus.

[bluebrown]

Someone in the go slack channel pointed out that the generated go sdk is using the pkg/, path prefix.

Since internal has been introduced, there is no need for this anymore. In fact, it is noisy and considered an antipattern, by the community.

Historically, the pkg directory was used to indicate the public API, of a module. However, with the use of internal, this can be inverted. Your entire module is public and the parts that shall not be exposed will be guarded with internal. There are more nuances to it, but that's the gist.

[kfcampbell]

Someone in the go slack channel

Which Slack are you referring to?

it is noisy and considered an antipattern, by the community.

Full disclosure, it was my call to use pkg. Normally in a library or service such as this, I'd use the domain name (e.g. if running something called code-scanning-service, I'd use the name code-scanning as a top-level directory for Go code). In this instance, I judged github and octokit to be both confusing and redundant, since both are present in the module path anyways and the meaning isn't immediately obvious. I can't use internal as a top-level code directory, since every consumer needs to import packages from there.

pkg may be a bit old-fashioned, but I think it's perfectly valid and I don't agree it's an antipattern. If you have links I can read more about this, I'd appreciate it!

Historically, the pkg directory was used to indicate the public API, of a module.

Where are you reading this? I did not believe this to be the case and I can't find sources to back this up.

[bluebrown]

Hi, sorry, I mean this slack https://invite.slack.golangbridge.org/. I cannot point to specific resources regarding pkg being used as public API. This is trivia that I have picked up over time.

I am observing the use of pkg being discouraged, frequently. And as mentioned it got right away pointed out.

Personally I don't think it's a big deal, but I thought it's worth bringing it up as it could potentially still be changed at this early stage. If it had greater appeal to the users, it may be worth considering.

Regarding your struggle, with the directories. There is a third option, which is to move everything you have right now one level up, (removing pkg). So you treat the repo root as the actual module root, containing packages, instead of using the pkg path as an artificial root. You don't need to pick, and we won't have any stuttering or noise in the path, neither double github nor pkg.

[kfcampbell]

There is a third option, which is to move everything you have right now one level up, (removing pkg).

I actually had it set this way at 93a9f512e6d552505b6441c7631f559627ff850f, but I don't like it: IMO the repo root should remain less cluttered to allow non-domain material to remain accessible, like .github, any scripting, CONTRIBUTING.md, the license, go.mod, etc.

I also considered using src, though I don't love that either.

[Meroje]

The generated go import aliases make reading the godoc much harder, basically forcing you to hover every link to see where a type is coming from.

see: https://pkg.go.dev/github.com/octokit/go-sdk@v0.0.4/pkg/github#pkg-types

[kfcampbell]

I agree this is a hassle! This is handled by our underlying generation engine, Kiota, and we don't have a way to change this at the current time.

[sluongng]

Just a personal take here, but I don't think I would use this.
I don't know about .NET, but for Go the API in https://pkg.go.dev/github.com/octokit/go-sdk is very not go-like.

Let's start with the package names

github/repos/item/item/pulls/item/merge
github/repos/item/item/pulls/item/reviews
github/repos/item/item/pulls/item/reviews/item/dismissals
github/repos/item/item/pulls/item/reviews/item/events
github/repos/item/item/releases

which have obvious problems.

Then the code is just... bad?
For example, https://github.com/octokit/go-sdk/blob/8bbee739c47d584632518b8b014a61f643c2c4c4/pkg/github/repos/item_item_actions_artifacts_get_response.go#L4 is not parsable at a glance, which is the whole point of using Go (simplicity, readability).

Could you tell apart NewItemItemActionsArtifactsGetResponse and NewItemItemActionsArtifactsResponse at a glance? I could not.

Finally, the doc here is clearly meant for another language

// ItemItemActionsArtifactsResponse 
// Deprecated: This class is obsolete. Use artifactsGetResponse instead.
type ItemItemActionsArtifactsResponse struct {
    ItemItemActionsArtifactsGetResponse
}

There is no class in Go, and artifactsGetResponse does not exist in the repo.

[kfcampbell]

I hear your (valid) criticisms. For me, I'm looking forward to this project in spite of the issues because a) Kiota will continue to get better, and so the generated code will improve over time, and b) this project is a huge improvement for SDK coverage over the existing state.

Thanks for sharing!

[kfcampbell]

Also, fixing the "class" language and naming the correct type is important, but do you have other thoughts on how you'd structure such docs comments?