Contributing to the SDKs

#1

So the purpose of this topic is to discuss and try to come up with a more consistent API when it comes to our SDKs.

Over the past few months the various SDKs have seen many changes being made to them, however, these changes have ended up causing the SDKs to expose slightly differently APIs from the other languages.

For example, an update in the .NET SDK to check if a transaction might have led to the creation of a new method to check if a transaction was refunded. But that method has not been propagated into the other SDKs.

We need to come up with some Framework to ensure that we propagate these changes to the other libraries. Same thing applies to updating docs, when changes are made, how does the community go about updating the documentation? PRs on documentation repo maybe? Or should Paynow provide a resources for handling those updates.

These are the kinds of issues I was hoping we could address in this topic.

Design changes on java sdk
#2

:muscle:, i concur with you, it would be very beneficial for both the community and Paynow.

SUGGESTION
If paynow is not willing to host repos for the SDKs, i think maybe they’ll hear us out when we setup the repos ourselves on Github for example Paynow2

#3

Thanks for starting the discussion @iammerus. Just as @root does, I concur with you too as we do require consistency across the Paynow SDKs otherwise with time the SDKs would grow to be very different.

My suggestion is we create a document that describes language agnostic guidelines to communicate how we should contribute to the SDK. In line with this, we could create a Contributing.MD file and have it stored in each repository. I will get started on a draft and then share it in this discussion. When Paynow team and SDK project collaborators all agree on the content, we could then add the file in each SDK project.

What are your views on this?

#4

@tzifudzi, that would be awesome. So you can draft up the contribution guidelines document and share it here. We can then work on it changing a few things if need be.

That should be a great place to start.

As for the documentation issue, @paynow. Let’s say a PR has been merged into an SDK and that PR changes the method signature of a particular method in an SDK: That change needs to be reflected in the docs. So that people are not reading up and consuming obsolete information. And this is a big one. The docs are already quite a bit behind as things stand. It would be great if we could come up with some way to address this

#5

@iammerus I’ll share the first draft soon. I’ll also make sure what you mentioned about the method names is included in the first draft.

#6

Awesome! Thanks hey,

#7

Awesome discussion you’ve started here guys! @iammerus @tzifudzi @root

A contribution and style guide is something we’ve been meaning to draft and put together for a while now following suggestions from @michaeldera. Unfortunately, resources on our end have been a bit difficult to put together for that exercise due to other project commitments - so the community stepping in to assist is more than welcome :smile:

With regards to the opening up the documentation for facilitating faster updates whenever changes are done to the SDKs we will migrate the docs source from GitLab to GitHub as it seems that’s where most of the community already is. This will allow anyone willing to contribute to open up pull requests that’ll be reviewed and ultimately merged into the master repo. A CI/CD setup to allow for on-the-fly (on merge) compilation and deployment to https://developers.paynow.co.zw is also being considered.

Looking forward to seeing your draft @tzifudzi and getting this going as it will help define the direction this community goes.

#8

Hey how is the draft going ?

#9

Hi @root! Sorry for the late response. I’ve been busy lately at work but I am going to find time over the weekend to share something by Monday. Feel free to share something as well if you can as I can always add my thoughts to your draft as well.

#10

@paynow @iammerus @root @michaeldera I am happy to report back that I have completed the first draft of the contribution and style guidelines!

I look forward to seeing your reviews and suggestions on how to improve them. Look out for the hyperlinks in this discussion to the actual docs which are in my Google drive. Perhaps a better way to collaborate on the docs going forward is to have the files on GitHub?

Take note that as a Java programmer, I may have been biased in my approach to the document, so please lookout for such biases.

How this could work

In the Paynow docs repo, I propose we have two files:

  • CONTRIBUTING.md
    • this doc will describe in detail the coding style guidelines that all SDKs should make an effort to adhere to
    • to cater for cases where a language may have specific requirements, these can be shown in a CODING-STYLE.md file located in each SDK
  • README-BLUEPRINT.md
    • this doc will serve as a guideline as to how the README.md in each SDK should be structured

In each SDK, we could have:

  • CONTRIBUTING.md
    • this doc will simply reference the CONTRIBUTING.md in the docs repo so that we have one centrally located file
  • CODING-STYLE.md
    • the CODING-STYLE.md will serve as a style guideline specific to the SDK, since for example some best practices and design patterns may differ per language
    • the sample file referenced is the file I propose for the Java SDK repository
  • README.md
    • the typical README.md that already exists in each repository
    • it will follow the defined structure in README-BLUEPRINT.md
#11

Oh and in response to your suggestions, I believe it makes sense to move the docs source to GitHub as well since Github seems to be more popular amongst the Paynow community.

And I like the idea to have a pipeline that deploys changes immediately to the developer hub. That’d make the process of updating easier and quicker.

#12

Awesome :smile:, so i guess this is the part where we open pull requests

#13

Unfortunately the docs arent in a Git repo yet. But definitely Git is a better way to collaborate on improving the docs.

Any thoughts on the actual content and if you think this structure could work? Please share your views.

#14

Awesome :smile:, so do we have to wait for @paynow to add the docs or we should create a pull request for the files

#15

Paynow are ultimately the owners of the project so lets wait to hear from them.

#16

As a follow up to this comment you will be pleased to know that the SDK documentation is now up on https://github.com/paynow/docs and you can go ahead and start recommending corrections via PRs and Issues.

Once one of the maintainers/owners of the repo reviews and accepts a PR the docs site will be automatically rebuilt and deployed with the new changes.

We are aware that the documentation has lagged quite a bit as changes and bug-fixes have been applied to the various SDKs so we are hoping that we’ll be seeing a lot of updates in those sections in the coming weeks!

#17

@paynow Great news that CI/CD has been achieved! Kudos to you.

We now have one last issue to conclude, which is that of the coding style guides to ensure consistency across the SDKs. See the doc I had prepared in above comments.

#18

Awesome and after that we’'ll see how we can get people to engage into contributing

#19

Is there a way to integrate Paynow with Flutter Apps. Using Dart or something?
Or even using React Native?
My email is tm6@williams.edu: Tafara Makaza

#20

hi there, been trying to implement one for flutter but i’m stuck on the iOS side of things, not really Swift fluent but i think for now building a dart client would be the way to go.