What is your opinion about outsourcing larger scripts from answers to GitHub repositories?

Question

Occasionally I write larger scripts (sometimes far over 100 lines of code) to answer questions on the site.

If I believe they are useful for more people or in more cases than the specific question is about or if I am going to maintain and update it every now and then, I prefer to put the whole code into a GitHub repository and link that in my answer instead of dumping the code there.

Of course the answer still contains detailed explanation and instructions to download it from GitHub and how to use it.

---

What do you think of outsourcing big enough scripts to GitHub?

Here are the pro and con arguments I can come up with, trying to ignore my personal opinion in favour of using using GitHub:

Pro:

• shorter answer:

  • easier to read, people don't "TL;DR" (do not read it because it's too long)
  • consumes less space, other answers below have a higher chance to also get read (people do not like to scroll down too far)

• easier to get code:

  • you can download the whole repository as Zip archive or download single files of it
  • no need to copy large snippets out of code windows in the answer, paste them in a text editor and save them under a specific name
  • if you have set up git and know how to use it, you can simply clone the repository to your local machine and even have all file permissions preserved.

• easier maintainability:

  • the author can have a local git repository, edit it with their preferred IDE and directly commit and push the changes to GitHub. No need to look up the answer and copy/paste and format the code.
  • no risk of forgetting to update the answer on code changes
  • code is not stored duplicated

• more flexible:

  • GitHub allows adding any number of files, including further documentation, examples or more script files
  • GitHub allows controlled contributions from other people

• better usability for newbies

  Imagine you are a rather new user who simply wants stuff to work and does not care too much about the details. You only have a very basic IT knowledge and just want something to double-click, not its entire code - I guess this is the average Ask Ubuntu visitor.

  Now from the perspective of this user, compare an answer saying

  "I made a script for this problem and published it on GitHub here (→link). Simply download this (→link) file and make it executable (chmod etc.), then you can run it."

  with another one like

  "I made a script for this problem. Simply copy the code below, open your favourite plain text editor, paste it and save the file as xy. Then make it executable using chmod etc. and you can run it.

  Huge wall of code which you don't understand at all
  

Con:

• Answer does no longer directly contain all relevant information, one could argue that it is a link-only answer.
• The link might die and the script may no longer be found. That's the main reason why link-only answers are not allowed.
• It requires an additional click to get the needed information.
• You need to leave the site to get the needed information.

---

You see that I'm personally very much in favour of using GitHub to store long scripts, but what is the opinion of the community? Please share your thoughts.

Answer 1

The general philosophy on SE is that answers should include everything needed in order to understand them. Sending people elsewhere for their answer should always be avoided. That way, even if the rest of the internet is destroyed and only SE survives, the answers will still be available. So, personally, I feel that code should always be posted in the answer itself unless it is too long. My take on the pros and cons you mentioned is:

Pro:

• shorter answer:
  • easier to read, people don't "TL;DR" (do not read it because it's too long)

Not really. If I need to visit another website in order to read your answer, then it's harder to read. By definition. If I read an answer but have to go somewhere else to actually get what I need, I haven't been given an answer.

• consumes less space, other answers below have a higher chance to also get read (people do not like to scroll down too far)

I don't see how this is true. Long code blocks are automatically truncated and presented in a scrollable box. In other words, whether you post 37 lines or 10000 , the size of your answer doesn't change.

• easier to get code:
  • you can download the whole repository as Zip archive or download single files of it

Again, if I have to go somewhere else, download a zip file (or learn to use git checkout), unzip it and then try to use it, it is obviously much harder than simply copying it directly from your answer.

• no need to copy large snippets out of code windows in the answer, paste them in a text editor and save them under a specific name

Yes, this is true, but it's a bad thing as I explained above :)

• if you have set up git and know how to use it, you can simply clone the repository to your local machine and even have all file permissions preserved.

Which, again, is way more complicated than copying a few lines of code from an answer.

• easier maintainability:
  • the author can have a local git repository, edit it with their preferred IDE and directly commit and push the changes to GitHub. No need to look up the answer and copy/paste and format the code.
  • no risk of forgetting to update the answer on code changes
  • code is not stored duplicated

Agreed. However, you can always include the first version in your answer and mention that the program will be updated on the relevant git repository. The best of both worlds.

• more flexible:
  • GitHub allows adding any number of files, including further documentation, examples or more script files

Yes, it does. And if your answer involves a large project, with many files, then of course you can't paste it all here. We're only talking about single scripts. Anything more and you don't even have the option of posting here, it would get far too complex.

• GitHub allows controlled contributions from other people

So does SE ;)

And your cons (including the rebuttals from your answer):

Con:

• Answer does no longer directly contain all relevant information, one could argue that it is a link-only answer.

  I say this is not true because all answers that advice installing a software X from anywhere would then be link-only as well - they only contain instructions how to install and use that program, but not the program itself, right?

Well, yes, but we have no control over those. Here, we're only talking about your code. If the answer is an already existing piece of software, you have no choice but to link to it. However, if that software is a simple script that can fit in an answer, you should also include the source in your answer. If it isn't, or if the source is not easily available, linking to it is the only solution. That's not the case with your code, you can choose where to put it.

• The link might die and the script may no longer be found. That's the main reason why link-only answers are not allowed.

  I say there is no higher risk of a link to a GitHub repository to become obsolete than of a Launchpad PPA to get deleted or a package to become no longer available in any other way. GitHub is safe and will not quit business within the next years.

That's what they said for Google Code and Source Forge. One's dead and the other is dying. Again, we can't control external sites. In the world of SE, the only safe place is SE.

• It requires an additional click to get the needed information.

  I personally prefer three additional clicks to download a file over a long click-and-drag to copy all the code from the answer's code block and nothing more. There are also wget or git commands that download the file directly - as simple as running apt-get install to get regular software.

Fair enough. I personally prefer anything over an extra click, let alone three.

• You need to leave the site to get the needed information.

  So what? If you can trust Stack Exchange, you can also trust GitHub. It's not a shady download site but the world's most famous place where open-source code is stored.

It's not a matter of trust. It's a question of adding more steps between me and my answer. In any case, there is absolutely nothing trustworthy about github. They don't review code. I could post code that destroys your computer, opens a backdoor or any other kind of virus and/or trojan on github with no problem. Here, however, we do review code. If the code is on github, it is far less likely that anyone will look at it and downvote you if you're doing something malicious. So some poor newbie might download it and brick their machine. If the code is here, we can review it and downvote it as necessary. So, if anything, github is less secure.

---

So, as long as your answer's code is simple enough to be self contained in a single text file and doesn't need linking or calling of other sub-scripts, it is better and simpler to have it here. Obviously, this is not the case for more complex code already hosted on github.

If you want to also maintain the code in your answer, by all means include a github link as well. There's just no reason to have that replace your answer.

For more details, please see:

• Your answer is in another castle: when is an answer not an answer?
• Strategy to handle answers containing GitHub links

Answer 2

I strongly believe answers on AU should be self-contained, complete and independendly usable. External links can be useful to add interesting stuff, to link to a more advanced version of the script or a possible ppa, but the answer should still work without.

Scripts, why not (only) post elsewhere?

If you post an answer to my question with a script, I want to look into the code, make an educated guess on the quality, see where it has downsides etc. Even more inportantly, I want other users to look into the code and see possible issues, be able to comment on it and suggest improvements. The joined knowledge is one of the most important fundaments of the site. Improvements are suggested to all answers here, including scripts.

This process is unlikely to happen if the code is not directly visible and readable in the answer itself.

Difference with existing software

The comparison with established software is invalid. Not only is established software less likely to have major issues, but if there are, more users will have run into the same issue(s), and can share their experiences. At the same time, posted scripts are by definition in an experimental stage.

Last but not least: the more parties are needed to make the complete answer available, the more likely it will sooner or later break; the weakest shackle defines the reliability of the entire answer being available.

Answer 3

As a normal user of Ask Ubuntu , I would love to see complete answer here instead of GitHub.

Assume a situation you have renamed your repo name and that code you have there will answer some question at Ask Ubuntu , do you have enough time and memory to remember all those answer what you pasted and correcting with proper repo name in each post ? I am just asking my friend as friend.

I dont know whether GitHub really go for maintenance but what you will do if GitHub really go for maintenance. Your answer wont do justification with out your code which in GitHub.

what If a crazy hacker , hacked your account and deleted all repo's ?

and many more cases my friend and those thoughts are thoughts which I found valid to me.

I respect your opinion as well.

Thank you.

Answer 4

As I realize the strong preference to keep the answer complete without relying on external links, I propose this IMO reasonable compromise:

The answer on Ask Ubuntu should directly contain at least a minimal working version of the script that solves the problem and meets the OP's requirements.

Additionally, the answer can contain a link to an external source like GitHub, pointing out that a newer and more extensive version of the script may be found over there.

The GitHub repository can then easily be maintained and receive updates, improvements, additional features and minor bug fixes.

The code snippet in the answer will not necessarily have to be kept updated, except major bug fixes that are needed for the script to work.

Answer 5

As I have already explained my pro GitHub arguments in the question, I'm going to rebut the con arguments I mentioned here:

---

• Answer does no longer directly contain all relevant information, one could argue that it is a link-only answer.

I say this is not true because all answers that advice installing a software X from anywhere would then be link-only as well - they only contain instructions how to install and use that program, but not the program itself, right?

If the whole internet breaks down and only Stack Exchange survives, any answer advising to download software from the official repositories, Launchpad PPAs or any other online place would be gone as well. There's clearly no difference to an externally stored script.

Or on the other hand, are suggesting that if I do not upload my script to GitHub but package it and upload it to my Launchpad PPA, that would change the value of my answer telling you to download and run it?

• The link might die and the script may no longer be found. That's the main reason why link-only answers are not allowed.

I say there is no higher risk of a link to a GitHub repository to become obsolete than of a Launchpad PPA to get deleted or a package to become no longer available in any other way. I consider GitHub to be pretty safe and stable and it will probably not quit business within the next years.

• It requires an additional click to get the needed information.

I personally prefer three additional clicks to download a file over a long and careful click-and-drag to copy only all the code from the answer's code block and not too much or too few.

There are also wget (or git) commands that download the file directly - as simple as running apt-get install to get regular software. That isn't an additional click then either, you need the terminal to chmod +x anyway.

• You need to leave the site to get the needed information.

So what? If you can trust Stack Exchange, you can also trust GitHub to be a non-malicious site. It's not a shady download site but the world's most famous place where open-source code is stored. The trustworthy of the site itself does not allow conclusions about all code pieces they host though.

Of course code on GitHub is not really reviewed or rated, but is it on Stack Exchange? There is no guarantee here either that anybody thoroughly checked every line of code I posted for correctness or security issues, even if the chance is higher.

However, those who would review hundreds of source code lines directly in the answer can also review them on GitHub and file an issue report there or comment below the answer where I post about it here on Ask Ubuntu.

Answer 6

In disagreement with externally-linked scripts, custom-built for an answer: consider the user model of SE:

• Anyone comes to the site with a question
• Optionally creating an account, they ask a question
• Getting answers convinces user to get an account to engage
• With an account, the user can interact almost-completely with the site (with more complete features with additional reputation)

Thus, this new user with exactly zero other internet presence, should have the power allocated for them in interacting with the responses to their question. Mostly that being the ability to propose edits to any content, the answers on their newly-asked question in particular, that has full access to the content that (almost) provides the desired solution/information.

Typo in an answer that yields a non-functional edge case? SE: propose edit with reason, wait for approval, done (otherwise, comment). External anything: good luck (what if you put the code in a blog post linked to a GitHub Pages? That's technically something you could pull-request against.).