What is the future of this repository?

[JonruAlveus]

This repository represents a dotnet wrapper around the GitHub api. I’m wondering what the future of this is? Given that nothing seems to be being added to the api, is this Repo in sunset mode where we make it work as well as possible or are we actively pushing for the fullest implementation possible? Basically I’m asking what the future of the v3 api is.

There has been mention of using the open api spec to build the models automatically, which sounds great. Would it be possible to build the code to call the endpoints automagically as well (even if we then wrap them up in clients etc. Could we also automagically create documentation and code comments from this?

Are we also looking at standardising all of the test methods? At the moment a lot of the integration tests don’t run at all. Would there be scope for GitHub to provide a number of accounts we could run the tests against (free, paid and enterprise) as we’re limited to running against free from what I can see.

What dotnet versions are we aiming to target going forward? I believe we should target at least the 4.6.1 or 2 to get access to the newer technologies. If we did that we could just target standard 2.0 as 461/2 is compatible. But, we don’t then get access to lots of the newer performance related improvements, so it’s a bit of a conundrum there.

Reactive Extensions feels like a bit of a pain, do we know how much it is used? Could it be something that is spun off into it’s own Repo or detached from the main code somehow? At the moment each route needs implementing in the main code and then in reactive. Also the latest reactive version targets .net 472.

Sorry for all the questions, I needed a place to vent!

[timrogers]

The GitHub REST API (sometimes called "V3") is very much still in development, and is being added to and improved every day.

We definitely want to make an active push to have the fullest implementation possible, and at least from a GitHub perspective, we believe that the best way to do that is with auto-generation from our OpenAPI specifications. That would, I reckon, cover the models and the client code too. Of course, we want to involve the community in this work.

Thank you so much for taking the time to write this, and for your contributions to the project - I really appreciate it. I'll let @nickfloyd answer your .NET specific questions, as he is much more of an expert on that than me!

[JonruAlveus]

The GitHub REST API (sometimes called "V3") is very much still in development, and is being added to and improved every day.

We definitely want to make an active push to have the fullest implementation possible, and at least from a GitHub perspective, we believe that the best way to do that is with auto-generation from our OpenAPI specifications. That would, I reckon, cover the models and the client code too. Of course, we want to involve the community in this work.

Thank you so much for taking the time to write this, and for your contributions to the project - I really appreciate it. I'll let @nickfloyd answer your .NET specific questions, as he is much more of an expert on that than me!

Firstly thank you for the prompt response, and apologies for thinking the API was shutting down. I had read in a few places that all effort was going into GraphQL and that the API wasn't being added to. I'm glad to hear it isn't! I believe automation and generation can solve a huge number of operation difficulties (and add their own of course) but it would certainly allow us to take the SDK to new heights!

[nickfloyd]

Hey @JonruAlveus,

Thank you for all of the questions. I'll do my best to answer them but know that our purpose here is to make the future of this thing what we want it to be, and what the community needs it to be - so when I say that I am grateful for your help in getting this SDK there and that we need folks like you - I cannot overstate that enough! Thank you! ❤️

Let's talk about Code generation, interpreters, and language interpolation

As you know there are loads of things that we can do here - especially given the power of .NET and reflection. Just two thoughts on the cautious side of things here:

1. Just because we can generate things, it does not mean we should. As we roll through discovery on all of this we might find out some areas where generation would be trying to put a square peg in a round hole. We need to have the courage to stand down when needed.
2. Our long-term goal should be language and platform independence. Meaning, we might nail down incredible generative aspects for the .NET SDK but we should always be targeting things like versioned, package distributed, models that the core SDK can reference as well as a generative engine that could potentially generate the models and implementations based on language templates, RFCs, and the like for any reference language - so generating models and SDK methods should be doable for both .NET and Go (for instance) using the same "engine" if possible. It's lofty but I feel that it could be possible.

So what might the future look like for code generation given the above statements? Let's have a look a what might be a really naive/potential roadmap (again we need the community's input and involvement here - which is why I am grateful for the questions):

1. Make sure our current solution addresses the community needs: All SDKs have been synchronized with the current API surface
2. Standardize implementations - testing, models, API methods, etc... (this is a critical step to get us to generation)
3. As we go through the above we will learn more about what works and what doesn't. Armed with that knowledge, begin prototyping generative models for each SDK
4. Solve OpenAPI generation for at least 1 SDK and implement - again with our sights on other languages
5. Publish (but don't reference yet) SDK models to packaging platforms (in this case nuget)
6. Work on Generative API implementations - methods etc..
7. Model generation is unified in the SDK (i.e. we used the published / versioned models in the SDK) and published to package platforms.

After this point, things get really interesting with things like:

• Recipe and workflow generation - think of things like plugins for the SDKs to do things like instantiating project boards with teams and referenced repos all in one SDK call. Think of your recent findings with reactions - SDKs shouldn't be reflective API implementations, but rather tools that simplify our approach to getting things done.
• We could start generating SDKs using language specifications - imagine pairing our OpenAPI specification with a language RFC to spit out a baseline SDK that could be extended.
• Generating language agnostic SDKs - what if we could maximize code reuse by implementing interpreted recipes or code
• Building workflow interpolation based on user patterns present in GitHub - this comes back to the community and GitHub joining up to make consistent workflows no matter where the users are - in community apps or GitHub proper.

🤔 The above is just me thinking out loud so I know there are many more things we can do or more clarification we could sketch out on what's mentioned above - the point is that by doing this together we can make some seriously cool software that will help so many people!

Let's talk about standardization

Oh man, this is where my ❤️ is! I love patterns, code standards, and the like when they make sense. I ❤️ them for two reasons:

1. It lowers the barrier to people walking up to the software and being effective in contributing or understanding why things work the way they do.
2. It takes the mundane and get's it out of the way for innovation - the more the basic things get standardized, the more they can be generated, and the more we can focus on innovation.

Standardizing the code here will be a critical path to getting us to the point of generating what needs to be generated.

Let's talk about .NET support

This is my line of thinking on this and I might be way off but I feel before we "sunset" or adopt newer versions we should have at least one version of generated models and API methods. Why is that important? I feel that it is because all current and even some future SDK users should get the most up to date implementations to get the most out of the SDK. This way we can move forward with progress in mind instead of dragging the past around while also honoring those who need those older versions of the SDK/.NET.

What's the best way to do this? I don't know just yet - I feel like discussions like these will help get us there!

Let's talk about 2-3 different .NET SDKs

Practically we have 3 SDKs that currently serve our .NET community:

• Octokit .NET
• Octokit.Reactive
• Octokit.GraphQL

We have a couple of other implementations but the above makes up the lion share of our user base.

What I understand from the early days was that there was a need for both a task-based versus observable-based API.

I asked @shiftkey about this (one of the earlier owners/maintainers) and he provided some excellent history on it:

GitHub for Windows used Reactive Extensions heavily through the ReactiveUI framework https://www.reactiveui.net/ and we wanted our GitHub API usage to work alongside that pattern. But we knew most of the .NET community did not want to also use Reactive Extensions (this was started before async/await was a part of C# and it became much easier to work with tasks), so we split the API surface into two:

• task-based API in the main Octokit package
• observable-based API in the Octokit.Reactive package (which depends on Octokit)

Regardless of the original intent was, there are some things I feel like we need to dig into and ask the following:

• What aspects of the SDKs are still needed and meaningful?
• When generation becomes a feature of the SDK set will these other aspects need generation? Should we generate them?

The bottom line is that we should stop doing anything that no longer makes sense and do more of what does make sense 😉.

Please let me know your thoughts on the above. I know it's a lot, but I just wanted to share what has been on my mind for a while now based on the questions. I hope we can continue the discussion and crank out some actionable things as a result!

[JonruAlveus]

Thank you for your response to my length and globally scoped questions! 😉

Firstly, very happy to help. I've really enjoyed spending my time on this community project and I can see it has a bright future!

I think from what you are saying, we're aiming in the direction of being able to generate whatever parts of the SDK we can for as many languages as possible. That's quite a goal! I can't say I have any real experience with code generators, but I've seen Liquid used (in the NSwag repo) or Handlebars, is that the kind of thing you mean? Once that's all done, we move into making the SDK actually do useful stuff rather than being an open book that people dip into. Very nice! With regards to your first point "All SDKs have been synchronized with the current API surface", I think repo has quite a way to go for that to happen.

I too ❤️ standardisation!

Ah so reactive was there pre-async... ok. But as you say, most of that could well be auto generated. Would there be any merit to merging GraphQL and .net into a central repository? Also what about the webhooks one?

Also, 100% agree with "The bottom line is that we should stop doing anything that no longer makes sense and do more of what does make sense 😉."!

I'll go get on with fixing some stuff 😄

[shiftkey]

On the naming side (everyone's favourite topic):

Practically we have 3 SDKs that currently serve our .NET community:

• Octokit .NET
• Octokit.Reactive
• Octokit.GraphQL

Some other history that I didn't get to touch on while we were chatting @nickfloyd that might help with future direction is that Octokit.GraphQL was started by a different team at GitHub to get access to newer APIs.

In my opinion the original Octokit package name is now confusing because Octokit itself predates our GraphQL API and only supports v3 - we didn't anticipate at the time that a "v4" API would appear that was radically different to the REST API. And then Octokit.Reactive falls into the same situation because we wanted an observable-based API instead of task-based.

I very much dig what @gr2m did on the JS side and split things out into a @octokit/rest and @octokit/graphql packages so you can choose which one you want, and I wonder if we could make this separation clearer in the future for the .NET bits.