GitHub Guidelines

Version 2

    Introduction

    OSIsoft is now officially present on GitHub! We think GitHub can really help to facilitate reuse and collaboration for the whole PI community in their projects. It also introduce version control which we consider important. GitHub  enlarges our current digital eco-system and adds a significant complementary piece to PI Developers Club and PI Square. We envision the whole PI community to not only take advantage of the shared projects, but also to share and collaborate with others.  This document walks you through the steps you need to take in order to take advantage of GitHub as a user or contributor.

     

    Where to Start?

    You can start by checking out our OSIsoft GitHub organization page. Here we already have added few projects and you can expect us to post more in the coming weeks. Another way to find PI related projects shared on GitHub is to search the PI Square Community for the github tag.

     

    Content is easily available

    Regardless of whether or not you have a GitHub account, you are able to browse the documentation and the source code. More importantly, from the main page of any project, there is a link to download a zip file containing the entire project source code: e.g. Visual Studio project files, documentation.

     

    License is very permissive

    We have decided to distribute our provided content using the Apache License 2.0 due to its clarity and permissiveness. We encourage you to use the same in your projects (not all open-source licenses are compatible); however, you can select your own if you prefer. In short, for projects applying the Apache License 2.0, it explicitly allows anyone to reuse and modify the provided content in your own projects.

     

    To apply the Apache 2.0 license to your work, simply follow the procedure here.

     

    This is just the beginning

    With this new addition, we believe our PI Community is now ready to consume, modify, and contribute to fantastic initiatives.  We are expecting to see publicly available applications, utilities, configuration files, scripts, and even more! Also, we hope these shared projects will give you ideas for contributions of your own to share as well.

     

    Overview of steps to contribute

    • Setup an account on GitHub
    • Create your repository
      • Create the repository on GitHub website with an Apache 2.0 license to encourage re-use
      • Add a readme file to give explanations about your project
      • Clone the repository locally on your machine
      • Add content to your local repository (directory)
      • Commit files.  Be careful because once committed, information will be public, so review everything carefully to make sure you are not publishing internal server names or any other Sensitive information in your repository. You can refer to this GitHub help page in case you run in such situations.
      • Synchronize (push) files to your online repository

    • Create a post on PI Square to explain what your initiative is about and share the link to your GitHub repository
    • Add a github tag to your post so others can easily find it

     

    Continue to read this document for more details on GitHub.

     

    What is GitHub?

    GitHub is a web platform that is widely used by the open source software community. GitHub's core functionality is based on Git, a free and open source distributed version control system. It is Git that makes all the magic happen by allowing users to contribute to each other’s projects.  GitHub has created a workflow that makes it very easy to collaborate working with Git.

     

    It is important to note that you do not need to be connected to the internet to work with Git and GitHub as indicated by the "distributed" word in "distributed version control system." This key aspect makes GitHub very convenient to use. You can simply clone a repository to your local machine and work offline until you are ready to push your changes to GitHub.

     

    When working with version control, it is a good practice to commit and provide a comment immediately after making small changes or adding a new feature. Ultimately, you’ll identify the level of granularity in the version control that works best for you.

     

    Git shines at tracking versions of files and merging changes. The most basic element that allows this is the repository, which contains all the files in a project and their change history. With GitHub, everyone can create public repositories for free. Furthermore, you can create a personal copy of any public repository by forking it. In this process, the copy will be automatically imported to your personal account where you can edit the project and keep track of changes. Once you have made edits to a repository, you can also request that those changes be added to the original repositories. This is where the collaboration starts!

     

    What do I need to learn to use GitHub?

    You can get started quickly by using the client GitHub Desktop. This client will allow you to commit changes you make to your local repository and push them back to your GitHub account. There are also several other Git third party clients that you can chose from if you prefer:

     

    Git is very easy to work with and there are many public resources to learn more about it. Essentially to get started, you simply need to setup a GitHub account and you can use the GitHub Desktop client.

     

    In addition to that, if you want to work or create community projects, you’ll need to use other features in the flow. You can learn more about creating a branch here which is a workflow technique that is helpful for trying out new ideas.

     

    Why should I start using Git and GitHub?

    We know that in many projects involving the PI System there are often similar configurations, scripts, and code that end up being created over and over again. What if you could be at the center of a collaboration that allows our entire community to benefit from what others have already done? This is where we see GitHub coming into play. When contributing, we ask that you talk about it on PI Square and apply the github tag to your post so that GitHub content can easily be found.  Here are some more reasons to start using GitHub:

     

    When forking other public repositories, I can:

    • Stay updated with the latest revisions of a project. As all you need to do is to sync the repository to update your local copy.
    • Inform the repository owner of changes I make (pull request) so he or she can integrate them in their repository if desired

     

    When creating my own repositories, I can:

    • Keep track of the changes in my files so I can refer to previous versions of my work at any time.
    • Share my work with documentation. The Readme.md found in most repository hosted on GitHub easily makes some public viewable documentation.
    • Allow others to quickly use and expand on my work.
    • Receive contributions and integrate them easily in my repository.

    You can also create teams around your repositories. This would allow others you trust to contribute directly in your code. There’s even more to discover beyond this as well.

     

    More Resources

    This document is only the beginning and we are very interested in your feedback to help improve. We will provide more information as needed. GitHub is a mature platform and there is tons of documentation, tutorials, and videos to help you get all it has to offer.  Hope you will enjoy this!

     

    Here are some helpful recommended resources:

    GitHub Help: https://help.github.com/

    GitHub Desktop: https://help.github.com/desktop/guides/getting-started/

    More learning resources: https://help.github.com/articles/good-resources-for-learning-git-and-github/

     

    Feel free to contact us as well: pidevclub@osisoft.com