I am kind of new to the open source world of Github, and I have a few questions about launching Julia modules.
I noticed almost all modules have a certain file organisation, e.g. src, docs, examples and test folders. Is there any assumption Pkg makes about the file structure when cloning it from Github, or when testing it? And how do the using and import commands deal with such a structure for local/private modules?
What is the purpose of the .travis.yml, appveyor.yml and .codecov.yml files?
I noticed most modules have a LICENSE file that does not really limit any action, which begs the question, why have a license file if you are not going to use it to sue anybody!?
Some modules have a different number of green, yellow and red indicators on their Github page for coverage, build, documentation, etc. How are these evaluated exactly?
I find .gitignore, NEWS.md, README.md, and REQUIRE self-explanatory but if you want to say a word about them for sake of completion, please feel free.
In addition to the documentation that @yuyichao linked above, I’d suggest playing around with the Pkg module. You can directly read the in-line docs from the REPL by typing a “?” before the name of a Pkg function. Or, if you like jumping in at the deep end, try (at the REPL):
> Pkg.add("PkgDev")
> using PkgDev
> PkgDev.config()
> PkgDev.generate("MyAwesomePkg", "MIT")
People generally like to know that the packages they write will work correctly on multiple platforms, but most people don’t have the resources to test across all platforms themselves. Travis and AppVeyor help with that (Travis for *NIX + macOS, AppVeyor for Windows). Codecov helps people keep track of how much of their package is actually covered by tests.
If you live in a country that adheres to the Berne Copyright Convention (you almost certainly do), then when you write and publish code it is automatically covered by copyright law, and anyone else is prevented from distributing, changing, or even (depending on which legal theories you ascribe to) running your code. Adding a LICENSE file gives others permission to work with the code you share that they would otherwise not have.
Also, while we’re on the topic of LICENSE files, please do note that every serious license includes a section in all CAPS that talks about warrantee blah blah fitness blah blah blah. THIS SECTION IS IMPORTANT! “Joke” licenses (such as the WTFPL) that do not contain such clauses can potentially leave you vulnerable to lawsuits if your code contains bugs. (To understand why, check Wikipedia for Implied Warranty of Merchantability.)
Every one of these may potentially be implemented differently, so without knowing which indicator you’re asking about it’s impossible to give a definite answer. Many adhere to the Shields convention and more info is available on that site.
.gitignore – Files/directories you don’t want to track with git
NEWS.md – Nice place to put a summary of what’s changed each time you release a new version
README.md – Good place to put a general description of your package
REQUIRE – Other Julia packages that your package depends on to work
I just thought of clarifying something. The reason I did not really google some of these is because I thought they had more to do with Julia than with Github, especially the files. And when I went over the documentation, I missed the part of packages. So admittedly I am at fault here but mostly unintentionally which is why I find the attitude of some of you offensive. I think the community here is extemely welcoming with many experts who may find it hard to put themselves in my shoes, but perhaps as the community grows and includes more professions, some may find this topic helpful. At least I did. What seemed to me like programmers-lingo is now something I can talk about, so that’s a step forward. Just wanted to keep it all cool
May I also ask the owner of the question to flag some answer as being the answer to the question?
I think @jballanc has compiled together a nice response. That should be selected as the correct answer, if @mohamed82008 does agree. Then, some other person would simply find the answer even among the pollution of private one-to-one discussions that does not have anything to do (directly related) with the question itself.
Here’s a suggested resolution to the discussion here. @mohamed82008 's question are typical of particularly non-programming-professionals coming to the julia package ecosystem. They can mostly be googled, most people do that, and it seems to be recognized as a convention that people should do this.
Even better, though, would be a document detailing all these things, in a public location that’s easy to find - after all, the answers and discussion here are potentially useful for many more people than @mohamed82008 - this usefulness would have been lost if he just googled everything.
My suggestion - maybe, @mohamed82008 you can take the answers here, the results of your own googling and the information you get by following the links, and write up a documentation piece entitled “Julia packages and Github”? I am sure that could find a nice place somewhere in the docs. And nobody would be in a better position to write it than you, because you are the one who best knows what doubts arise for newcomers. It’s a great way to pay it forward to the community.
I think the post by @jballanc and the video by @ChrisRackauckas do a great job at explaining most of my concerns regarding Julia and Github, so I don’t think there is much that needs to be added to what they said. And yes I vote up for including the answers to these questions in one place in the documentation, for sake of completeness, with links to some other external links for more info.
