What are the main functionality differences between Github Wiki and Readme,
Asking those that have used both readme and wikis extensively. So that we can better decide which to use for the purpose of outputing verbal information. This would be based on your answer. Thanks.
As examples, some have used wikis --
http://github.com/mbostock/d3/wiki
http://github.com/ParticleCore/Particle/wiki/Features
and some people have used readmes --
http://gist.github.com/atcuno/3425484ac5cce5298932
no better place to ask? -- meta.stackexchange.com/questions/157888/what-site-is-good-for-github-questions
Talking about a project repository :
Readme.md is the packaging
wiki pages is made for development/contributors documentation
gh-pages branch hosts user documentation
Both readme & wiki have no function, except for providing information. Github recommends you to create a README.md to display a short summary & usage of your repository, while the Wiki is totally optional.
I have to cross this bridge today, and in addition to this helpful thread I also found reading up the following helpful
https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
A key excerpt from there that I found useful and to the point
A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis.
Based on those and the other answers here, it makes sense to be high level in the readme along with all the getting started information (i.e. local setup), and leave the long form information such as application features, design principles, etc. in the wiki.
Another major difference of course is that the readme will get versioned whereas the wiki will not. Versioning of this doc is not a major concern for us, but it could be for you!
Related
I'm publishing a tutorial that includes a lot of code interspersed with documentation. I'm considering two ways of hosting the code:
Separate git repository with code files and markdown files explaining the code
Github gist containing both of these
Are there advantages of hosting in a gist v/s a repository? When would one prefer one of these over the other?
Gist is a simple way to share snippets and pastes with others.
Whereas Repo is simply a place where the history of your work is stored.
There is no good answer, it's personal preference. I make mine a conceptual distinction. If it's code designed to demonstrate a technique, teach a principle, or show off a solution it goes in a gist. Doesn't matter if it's one file or 30 files. If it's actual code intended to be run, used as is, or forked as boilerplate I put it in a proper repository.
If you use markdown files for your tutorial, now there is one important difference, even if you are only creating one file (and specially if it is a long one).
Since April 2021, .md files created in github repositories now include an automatic Table of Contents which greatly improves navegability. See this related SO answer for more info.
As far as I know, this automatic ToC does not exist in gist-created .md files, so I'd rather go for a repository in this case (OP mentioned "a lot of code interspersed with documentation").
Hello I'm new to Github/Gist and I want to use this code, but I need to modify it a little bit. Can i just fork this code and modify it to use it for my own projects? Or do i have to link to the author etc.? Here is the link: https://gist.github.com/learncodeacademy/777349747d8382bfb722
Thank you!
Github repositories are meant to be forked. You don't have to ask an author for permission. Anyway, the gist you linked to has already been forked 30 times.
When you are using a forked repository.It shows up as "forked from xyz". So attribution is automatic. But if you want to, you can always give an extra credit to the author by mentioning it specifically.
Forking a repository on Github, creates an individual copy of the code. This feature is meant to encourage collaboration as well as allow you to experiment with the repositories code. Forking can be used to propose new changes to someone else's code or jumpstart an idea or a new project. As the repository was created by someone else, it is always important to understand the limitations of using their code for your own projects (especially if you plan on selling this product). Every repository created on Github has the chance to create a license file. This file will tell you what you can or cannot do with the forked code. Often open source code is meant to be used and shared with everyone, but it is still good to check. Here is Githubs documentation on forking repositories: https://help.github.com/articles/fork-a-repo/. For more information on licensing files see http://choosealicense.com/. Github gists follow the same standard. If you are still worried, it does not hurt to contact the owner of the repository and verify that you can use it for your own projects.
The point of open sourcing code on GitHub is for others to take and use for themselves and learn from it. Also, like fuchsteufelswild said, when forking on GitHub it automatically gives credit to the author so you should be good.
May be a well known question, but actually I'm asking this, because I'm not familiar with these tags.
I've seen similar types of tags in various Github projects, especially in their README.md. My questions are manifold regarding these:
What's the purpose of these tags?
How to generate them?
Is there any good practice or documentation that suggests what types of tags can be used or should be used in a project?
When a project can be determined viable using such a tag?
What's the purpose of these tags?
These images are provided by external services, often continuous integration services, and are used to show interesting information about the repository.
For example, the first badge you show in your example says that the build is "passing" (the exact definition of this will be build-specific, but it commonly means that the tests pass and nothing blew up during the most recent build).
The third example, coverage: 12%, is a code coverage report.
How to generate them?
Each service will have its own way.
The second badge in your example is from Scrutinizer, and unfortunately I can't find documentation about its badges. But most badging systems work by giving you a link for each project or job that you can use on your website or GitHub or whatever, and when a build happens the badge's appearance is updated accordingly.
The Travis CI documentation contains a good example.
Having answered the first to questions, I think your last two largely disappear. The badges that can be used are determined by whatever services you can find. The badges that should be used are entirely up to you.
Previously I remember that I could go into any repository and see how many codes it has how many lines with or without comments, what languages is it made of with how much percentage, how many man hour was used for development of that repository. I could see all of them on my browser. No code was required.
Now, I cannot find any option on Github. Is this facility changed, moved or removed?
There is an open source project made by #vdaubry : Github Awards
You can get all the information you described and more.
I want to open the issues tab when I open repository because I made a repository just for collecting the tasks for all my project , How can we do that ?
As #VonC has said, this is NOT configurable. It seems that what you require is an issue tracker and not specifically a repository. This articles may help you find an issue tracker that fits your purpose:
http://mashable.com/2014/02/16/bug-tracking-apps/
http://www.thegeekstuff.com/2010/08/bug-tracking-system/
Github's feature for referencing issues in commits automatically just by using the # and referencing commits in issues using the commit hash id is powerful. But is it a maintainable or scalable approach to handle issues from different repositories in one central repository? I do not think so. Issues are important in project development and should be kept organised the same way we keep code clean and organised.
However, this does not mean that it is not possible to maintain your issues in a single github repository. Instead of trying to have the issues tab open automatically, you may create a manual, as a README, for instructions on utilizing the reported issues. This manual will be shown to users visiting the repo. See https://github.com/keybase/keybase-issues as an example. You may find this github article useful in referencing issues.
This doesn't seem to be configurable.
That means you need to open your repo directly at the "Issues" page:
https://github.com/<username>/<reponame>/issues