Source control integration was added as a feature to ServiceNow in the Geneva release. That increased by a wide margin the quality of development tools available to the ServiceNow developer. One could save code, easily move from instance to instance, backup personal developer instances, etc. One of the details of the implementation is that under the hood it is committing update sets. This complicates standard collaboration tools. GitHub pull requests and normal patch files assume that they are working on the text of code so when that text is really an XML payload, that presents a big challenge for diffing and merging. Because we both have XML and ultimately a checksum in order to make the integration work, you can’t just patch the XML and expect it to work. For all the reasons we tell people you can’t directly edit the files in your repository with an offline editor, you also can’t edit them with the standard GitHub tools. This means we can’t by default follow standard GitHub collaboration patterns.
Last week Josh Nerius (josh.nerius) and I attended GitHub Universe. We met a lot of people from GitHub itself and many from in and around their ecosystem. One of the companies that impressed us was Digital Ocean. They are currently sponsoring their Hacktoberfest challenge. In this they truly put their money where their mouth is and give away thousands of t-shirts to encourage collaboration in the GitHub world. For the month of October, anyone who registers and then submits four pull requests on GitHub will recieve a t-shirt. This is not having four pull requests accepted by well known open source projects, this is any four pull requests being created on any public repositories on the entirety of GitHub. They also don’t require they be production code. It could be documentation fixes or test cases. All they want is involvement.
While we were still at GitHub Universe, Josh had an amazing brainstorm. We were jealous of the tooling of many of our fellow attendees, and excited about Hacktoberfest. He thought up a scheme that would allow us to harness a significant portion of that power. We set about coding like crazy during every free moment that day (including asking the GitHub team directly for technical help on some of the integrations.) By the time we left we had a plan and a good bit of code written.
Over the last few days, we’ve been working to add integrations to GitHub from within instances using the same helper app we used at CreatorCon 2017 in Orlando to control forking and branching projects. To be clear, you the developer *do not need this app*. You only need it on the instance accepting the pull requests. I will now walk you through the steps to get yourself set up to contribute. These steps will be the same for any project. We have one we are beginning with (the one demonstrated during this Live Coding Happy Hours (Part 1, Part 2, Part 3 ) .
Step 1: Have a GitHub account created, confirmed, logged in and ready to go.If so desired, register to participate in Hacktoberfest.
Step 2: Follow the link to this repository (https://github.com/jnerius/sn-slack-points-thing) and create a fork of the project into your own GitHub account.
Step 3: From the instance on which you will develop, connect to source control and connect to your own fork of the project.
IMPORTANT - To work around an idiosyncrasy of the Git integration, you’ll need to do the following in order to get credit on GitHub for your contributions. The account on the instance from which you are doing the work and ultimately committing the changes needs to have a username and email address that matches the ones on your GitHub account. You might think that because you are authenticating with your own credentials that it would automatically get written as you but that is not the case. Without this account tweaking, you’ll see a lot of commits as “admin” or whatever account you use on the instance that won’t tie back to you, defeating the fun of Hacktoberfest.
In my case, I created a “daveslusher-sn” account on my personal developer instance from the Developer Portal, and set the email to my work address, both of which are the same as the GitHub account I wanted to use. If you look, you’ll see commits made from Studio that correctly registered. Before I did that, my commits came from the admin account and were connected to nothing.
Step 4: As you do chunks of work, create a feature branch for each one. In keeping with Git philosophy, we suggest you create a branch for each individual chunk of work and you keep them as small as possible. If you are submitting two bug fixes, do it in two branches and two chunks of work. The smaller the commits, the easier they are to incorporate back into the main project.
Step 5: When you are finished with your feature or bug fix, ensure you have committed all of your work. From GitHub, navigate to your feature branch. Click “Create a Pull Request” and use your main branch as the comparison. This will send a notification back to the original project owner who will examine and either accept or reject the changes. From their they will close the pull request. You may see extra files in the diff with sys_customer_update changed to true. Simply allow all of those to proceed forward from this point.
Note: if you are submitting a pull request based on an issue, enter it in the comment. It will automatically associate and you will see a dropdown showing the title to select it.
Step 6: After submitting 4 pull requests, collect your free t-shirt from Digital Ocean. ‘
For the Points Thing project in particular, Josh has filed some issues (https://github.com/jnerius/sn-slack-points-thing/issues) related to features and changes we’d like to make in this application. Previously, it would have been solely his responsibility for all changes since he was the only one who could reach the repository. Now if you’d like to play along, you can claim an issue, work on a feature and submit the request.
From the perspective of you the developer, all of our tooling is invisible. You just work and submit requests. All the code that makes this consumable by an instance is on the instance accepting the pull requests. For now, that is not in a state to be published widely but we hope to do that as well sooner rather than later. It’s complicated enough that it either needs to be simplified or a significant amount of supporting documentation written.
If you do want to submit code for the Points Thing bot, we have a slack channel devoted to both discussion of and tests with the Points Thing bot at the SN Devs slack channel. It is the #points-thing-dev channel. (Note, this is grassroots channel and is not an official ServiceNow resource.) We will be monitoring that channel for discussion and also kicking the tires of the bot there.
For those not interested in Points Thing or Slack integrations, here are a few more public repos to which you can submit if you desire:
- Service Portal widget demonstrated on TechNow 28 and 28 https://github.com/daveslusher-sn/TechNowServicePortalDemo
- Working With Webhooks lab from CreatorCon 2017 https://github.com/CreatorCon17/CCW3954-WorkingWithWebhooks
To reiterate, you the contributor do not have to do anything special in order to contribute patches (aside from naming the account the same as your GitHub user.) We have some special code running on the back end that allows us to accept these patches. In time and armed with our experience from this project, we will harden that and eventually release to the world via Share.
This not the end of this topic. There is more to discuss but this is plenty for a single post. Shortly we will include some information on how to keep your forked repository current with incorporated changes and some lessons learned. If you have any questions about this topic, feel free to leave them in comments and we will address them there and/or in future blog posts. This is standard operation in the open source and GitHub world but somewhat novel to the ServiceNow development world. We expect there will be questions and we’ll answer them as quickly as we can. October is ticking by quickly!
For now, let us know if you are participating. We’ll be watching the forks on GitHub and are extremely happy to now be able to collaborate with the same tools as most of the rest of the development world. Welcome to #Hacktoberfest!
Update: For the next step in contributing, check out the next blog post on how to handle your GitHub forks.