Skip to content
This repository has been archived by the owner on Aug 22, 2020. It is now read-only.

Latest commit

 

History

History
15 lines (10 loc) · 4.35 KB

Repo_Setup_Readme.md

File metadata and controls

15 lines (10 loc) · 4.35 KB

Setting Up Your Repos: Readme Markdown, Licensing, and .gitignore Files

Main Readme file:

You may have noticed that GitHub prompts you to write a "Readme" file when you make your repository. This is a special file written in "markdown" (the same way we write on the Issues board here), but it's saved and stored as one of the files in your repo, so it gets a .md file extension (which means MarkDown). The Readme.md file is sort of setting up a little sign in front of your repo to indicate what visitors may expect to find here. It doesn't need to be very long. (For our DHClass-Hub, I wrote up the Readme as a welcome to new students, but most Readme files are just a brief description.)

Multiple Readme files:

One thing that's fun about markdown files is that you can create them quickly from the web browser for your repo by using the "Create New File" button (to the left of the green "Clone" button on your web repo). I have actually posted multiple Readme files up on my Pittsburgh_Frankenstein project repo as explanations to my team and outsiders of our project decisions. (Try clicking on the files with the .md extension.) Basically we can use those files to write formal "documentation" of a repo out of things we hash out together in a discussion thread over on Issues. What we write on Issues board is sort of a giant, searchable scratchpad, but it isn't actually tracked and stored like the files in your repository. So that's why we write those extra markdown files to store in the repo itself.

License file:

When you start a repo, GitHub prompts you to make a License.md file, and gives you options to choose from. This has to do with how you want to share your files with others. GitHub as a community tends to favor sharing code openly because this is an environment where everyone learns and benefits from each other. That's definitely the spirit of our coding work in our course: we work openly because we're a learning site, and we learn from each other and welcome others to learn with and from us. At the same time, if we want others to credit us when they draw from our work, we can establish that in the license we choose. And we can also ask in our license that people who adapt our work also share the code openly just as we did. That's known as a "copyleft" license (different from copyright, though it does establish what we see as our rights to be credited. The idea of calling it "copyleft" is to say we actually encourage others to come and adapt our work instead of threatening to sue them for it. In the coding community, there's a long tradition of people learning from each other openly over the public web, and GitHub is very much a part of that, even in guiding people to read a range of "copyleft" licenses that lots of coders use.

You don't have to choose a license at first (or ever), but if you want to check them out, go to the website for your repo, click the "Create New File" button, and name it "License.md": When you do that, you'll see a "choose a license" invitation on the right of your screen: it's a dropdown menu, and you'll see a big list, with three major (often-used) licenses at the top. I picked the GNU GPL license just now for our DHClass-Hub. I haven't selected one for my other repos, but I'll give it some thought. The MIT license is super simple, and basically grants a visitor the freedom to do whatever they want with your code, including make a profit from it themselves. The difference with the GNU license as I understand it is, I'm saying if you want to use our code, feel free, but you have to share it freely, too.

.gitignore file

One more thing you may have noticed in setting up your repo is that GitHub suggests you make a .gitignore file. This is a special settings file which is really helpful when people share a repository who work on a mix of Mac, Windows, and other kinds of machines. For example, Macs automatically generate weird ._DSStore files that save in file directories and cause us problems sometimes when they are pulled in on a Windows computer. What .gitignore does is make a list of hidden automatically generated file-types that we don't want to be ported with our repositories. I've got a good .gitignore file set up on our DHClass_Hub, and I'll post it to each of your repos to share.