Background
Talis' Developer Community likes to share tools people have written to support each other. This article outlines a good way to share code and why this is a good idea.
We would recommend using github.com. There are other services available, but this is a popular choice in the modern dev world, familiar to most developers and users out there, and also a service that Talis uses ourselves.
Why is this a good idea?
So many good reasons:
- Shared solutions
- Sharing with the developer community allows your peers to see your achievements, which may be a starting point for them to develop their own ideas which they can then share back to the community as a whole.
- Shared support
- Writing and running something in your own environment is one thing. Taking what someone else has written and running it in your environment might expose issues that weren't a problem for the original writer. Or perhaps resources taken for granted may not be available to you. As these problems are discovered and resolved, the changes can be merged back into the community code to produce robust and re-usable tooling.
- Issues don't have to be answered by the owner of the repo, anybody who knows or uses the tool, or who just may understand the issues at hand, could help to debug and resolve.
- Shared innovation
- Tweaks, improvements, bug fixes, new features... these don't have to be authored by the owner of the repo, but others can 'fork' the repo, make changes, and then can submit these changes back to the owner as a pull request which can be fed back into the original code.
- Multiple people can be an owner of a repo and can collaborate, and they don't all have to be from the same University!
Creating your first github repo
https://help.github.com/en/articles/create-a-repo
Best practice notes
These are things which we would recommend you try to put in place. They help you keep things clean, portable and make it easier for other people to get up to speed with things.
Create a README.md file
Writing a README.md via Github gives you tools to write and preview how your file will look. This should include the following key things, and should use Markdown to format the file.
- Describe the problem you are trying to solve.
- Describe how your solution solves the problem.
- Give an example of using the tool.
- Give details of how to install and setup the tool for the first time.
- Detail any software required to be installed to make things work.
- Simple step-by-step commands are always appreciated.
- Add anything else you think might be useful!
Tenant Details
- Do include a way to tell your tool which tenant it is working with.
- Don't include your tenant's connection details in the code.
- Do provide a sample config file, or detail in the README.md the variables that need to be passed to the tool at run-time
Keys and Secrets
You wouldn't publish your username and password on the web. So make sure that you don't ever commit them into a github repository. It should go without saying that this is a security risk and it is easily avoided by:
- Using a config file.
- You can check a sample config file in, but then people can create their own from your template.
- Using environment variables
- Variables set on your operating system can be picked up by your code. You then just reference the variable in your code and we never have to see your secrets.
- Pass things on the command line
- If your tool can take command line options, use them to pass in configuration details.
Comments
Do include comments even if it seems obvious to you now why something is written the way it is. Comments should say why a particular decision has been made so that your future self will thank you for reminding them what that gnarly bit of logic is trying to do!
Required software
Make a list of all the things that are required to be installed to make it work. Share that in the README.md
Examples
People learn by seeing how you are running the tool. Give an example of running the tool (no keys or secrets visible please!!), but you might also include screenshots, videos or animated GIFs (redacted where necessary) to help convey how things work.
Give an example of output of the tool. This helps people to understand if the tool is working as expected, or whether they are seeing something unusual.