Procedure to update guide for .NET SDKs

Client SDKs .NET SDK
#1

I’m not sure whether it is more of a governance topic or client SDK, please correct me if I’m wrong.

I’m currently maintaining the .NET repository of the Parse client SDK and in the past weeks several changes were made and most likely further ones will be in the future.

Based on a big rewrite by Alex Fanat (TheFanatr) the guides and API documentations will become outdated or are already, depending which version of the SDK one refers to.

In preparation of any future changes I wondered how the procedure to update or extend the guide/API references on parseplatform.org would be done.

The last release of the .NET SDK included separate modules for various platforms (Unity, Xamarin etc.) and thus separate guides for .NET and Unity are available as of now. Regarding the new development release of the SDK there will be little differences in usage of the SDK and the guides may be combined into one.

Who is responsible for the guides & docs and can help me with my question?

Kind regards
Tobias

#2

I just moved the topic to the .NET SDK sub category, that should be good.

I manage the docs repo which contains all the guides but the API references are maintained independently by each SDK & Parse Server. Each of these repos has a gh-pages branch which contains the API reference which you can then see on docs.parseplatform.org. The api reference should be published automatically by Travis CI but on the .NET SDK it seems it is not working - generally happens due to permission changes - giving Travis a new GitHub token will hopefully fix this.

Currently we have a policy of the guides referring to latest version of the respective SDK. Ideally PRs are made to update the guides well before releases are made to give me & others time to review them, but this is only really important for the more high traffic SDKs & guides.

We could definitely combine the guides, if you or Alex can make a PR to address the content changes I can help with removing the old ones.

#3

I had a little dig and evidently the .NET SDK does not use Travis and looking at the commit history of the gh-pages branch it seems like it has never been automated.

#4

Thank you tom for the info and thank you for moving the topic to the subcategory.
I actually didn’t find that when creating but will take a more closer look the next time.

Is there anything I can do to put a github token into travis (never used it in any way) or can you provide it?
I’m not sure whether or not this is anything I can do or not. I’m glad if I can help and understand the processes a bit better.

Regarding the order of updates to code and guides, that is on me I suppose. I had little insight on the processes. I’ll put it on the .NET SDK project board to check the guide for changes required based on the last PR by alex.
As alex and me discussed on the repo itself, we consider the current state of the master branch a pre-release and have marked it as such on the releases section and on nuget.

Is there a way to provide guide and api references for both (in case of API it doesn’t look to me though when it should do it automated) the last version 1.7.0 and the new 2.0.0 or will we need to prepare the changes and decide to switch from the one to the other?
Or should changes for a newer version be included in the old guide and marked as related to the new version in some way? (perhaps I’m overcomplicating it ^^)

#5

I think you could generate a token for travis as it essentially allows travis to use your account so it can make commits. Although ideally we would have one community account that travis would use because currently we have the headache that if a maintainer moves on it breaks travis and we have to put new tokens in - I might look at doing that.

It would probably be best to open an issue on the SDK’s repo to discuss generating & automating the API reference as we will have to work out how they were previously generated etc.

Don’t worry too much about the guide, it’s great that you and Alex are moving things along and it’s not a major concern. Feel free to leave it until after you’ve finalised the 2.0.0 release.

With the current docs system it’s not practically possible to maintain multiple versions. When making changes in the guide its absolutely fine and often helpful to note if something is only applicable to say v2.0.0 and above but I wouldn’t stress about it; the history is always available on GitHub if someone needs to reference it.