In my previous article, I shared my thoughts on open sourcing the Sage 300 Web SDK (SDK) and how, in my opinion, this will benefit the Sage 300 Ecosystem.
In this article, I am introducing the SDK as Open Source Software (OSS) and will explain the changes to the original vision since the idea of open source was first presented along with the policies and procedures for the repository.
The SDK was pushed to the public repository on July 23rd, 2016. The goal was to make this available for our Sage 300 2017 Release (August 2, 2016) and to also have it available for Sage Summit 2016 in Chicago (July 25-28, 2016). We made it by 2 days!
The original plan was to use the Apache License 2.0 for our OSS. However, in discussions with our Sage Legal Team and the Open Source Initiative team, The MIT License (MIT) was chosen instead. The license can be found here: https://opensource.org/licenses/MIT
The GitHub Repository is SageNADev/Sage300-SDK and can be found here: https://github.com/SageNADev/Sage300-SDK
The administration of the repository is performed by Sage’s DevOps Team located in Richmond, BC.
The repository is read-only for anonymous users which means that these users cannot “push” their changes into the branches in the repository.
Collaborators are Sage assigned developers and personnel which have write/push access to the branches in the repository.
There are two main models for collaboration using GitHub:
The Shared Repository Model
The Fork and Pull Model
In the Shared Repository Model, in order to allow everyone to “push” to the repository, users have to be granted collaborator permissions. This is a good solution for small teams where members know and trust each other. This model cannot, or should not, be applied to large teams or a public repository where all users have the right to contribute.
In the Fork and Pull Model, any GitHub member can “fork” a public repository. When forking the original repository, another one is created. Modifications can be applied to the forked repository without the changes affecting the original repository until a pull-request is submitted and evaluated by a collaborator who may or may not merge the changes.
Therefore, with Sage in the collaborator role, the model of choice is the Fork and Pull Model.
See the following article on Forking: https://guides.github.com/activities/forking/
There is a difference between a fork for an anonymous user and one for a collaborator.
Story branches are where the Sage collaborators make modifications and enhancements to the next version of the SDK. However, on GitHub, the repository is either public or private and branches cannot be private in a public repository.
The branch where the work is performed is not ideally suited for public consumption from an interest perspective, but also from exposing the developer and potentially numerous changes.
Therefore, in order to take advantage of GitHub for both public and private development, a Sage collaborator will:
Fork the public repository
Change the settings of the new fork to private
Clone the private version down to their local machine
Create a story branch based upon the develop branch
Note: Story branches are prefixed with a Version One Story plus Description
Make changes locally
Commit to the local repository
Push up to the private fork
Use pull-requests to selectively copy the required branch (develop) to the public repository
The Sage collaborators use squashing in order to reduce the commit history being pushed into the public branch.
While Sage collaborators used a forked repository for making changes to the public branch, any anonymous user can submit changes to the public repository. However, an anonymous user is not able to commit or push these changes themselves since they only have read-only access.
Therefore, an anonymous user will:
Clone the fork down to their local machine
Push up to the fork
Submit a pull-request, which is evaluated by a Sage collaborator for inclusion into the public repository
The development branch (develop) is just what the name implies as it contains the in-progress contents of the SDK that is currently being worked on for the next release.
Sage collaborators are pushing changes and potentially merging anonymous requests for the next version of the SDK.
Only Sage collaborators can make changes to this branch.
This is the branch to be accessed based upon the following question: “Get me the in-progress version of the SDK that is not ready for release, but is to be released with the next version of the SDK”.
The current branch (master) is the branch which holds the current release of the SDK.
Sage collaborators may push changes to this branch in response to defects or issues either discovered internally or externally which require immediate correction. Any changes to this branch are also made in the develop branch.
This is the branch to be accessed based upon the following question: “Get me the current version of the SDK”.
The release branches (i.e. release-2017, release-2017.1, etc.) contain the contents for that particular release.
When the next version of the SDK is released, the current branch (master) is copied into a release branch (release-2017, for example), the development branch (develop) is copied to the current branch (master) and then the development branch (develop) becomes the basis for the next release.
There is only one in-progress branch: develop.
There is only one current version branch: master.
There will be numerous version branches: release-2017, release-2017.1, etc.
Only Sage collaborators can make changes to these branches.
The folder structure is identical between the development, current and release branches. The folders are used to segregate the various components of the SDK. The contents are different in that they contain content relevant to the version of the SDK that the branch represents.
This folder holds the documentation for the SDK and contains the following sub-folders:
This folder holds files, if any, regarding any patch work required to the SDK due to late minute changes that were not able to be included in the Sage 300 application. The README file in the patch folder will discuss the patch, the requirements and any steps necessary to apply the patch.
This folder holds the sample projects, which are standalone, runnable versions of different web screens and reports within the Sage 300 application. These samples are to provide implementation knowledge.
This folder holds the source files which comprise the wizards and utilities and contains the following sub-folders:
The branch root not only contains the folders just mentioned, but also contains the following:
A read-only file for displaying the MIT Copyright notice
A read-only file for displaying any SDK information on the main GitHub page
A read-only file for displaying the current version of the SDK
The SDK follows the release cycle established in the roadmap for the Sage 300 application. Therefore, new versions of the SDK are released when the application is released.
The approval process for changes submitted by anonymous users are performed by Sage collaborators who will review these changes for inclusion based upon the value added to the SDK for the benefit of all users.
Therefore, it is extremely important to provide as much useful information and rational to support the request being made. And, not all requests will be accepted. But, the good news with OSS is that the submitter can still enjoy their version of the SDK even if the request is not accepted.
Sage collaborators will review new pull requests on a bi-weekly basis.
Depending upon the SDK roadmap, Sage collaborators may be working throughout the development cycle on changes and enhancements and will want to potentially include any requests and issues discovered and presented by anonymous users.
The SDK is released to open source! This article covered the GitHub repository, the license strategy, and policies and procedures pertaining to usage and management of this public repository.
I am excited for the Partner and ISV community to participate and contribute to not only their success, but to the success of the SDK and to other users of the SDK. I look forward to the submissions from the community in modifying and enhancing the SDK.
As a standard disclaimer, any topic in this article is subject to review and doesn’t represent a commitment as to when it will be available.