Posted in Software Development, Uncategorized

Common Github Markdown and Hidden Files


The power of Github lies in not merely using it as a source control. Rather, the power lies in using it as source control, bundled with a means of social media. Different files, features and the vary nature of git are designed to be a social media-communication tool to convey information to developers and scientist (they use git too.) For example, tagging lets people know you have releases. Seeing a branch communicates to others you are working on something and do not want to affect a major branch (like fixing a bug or adding a new feature.)

In looking at numerous git projects, I have seen a number of files that are hidden (beginning with a period) or are markdown (ending with “.md”) that occur repeatedly and are not related meant for third-party dependencies (like .babelrc for babel.js). I do not believe there is a standard. Nevertheless, they tend to have similar information across different projects. Here are the ones I frequently see:

.gitignore: Files you do not want git to pull into source control.
You can find a pre-made file for your current project off this site: https://www.gitignore.io

.editorconfig: Instructs text editors that support this on how to format code. It is best to have this to prevent a colossal geek-battle between the guy who uses 2-spaces with another guy who uses tab- this file is the definitive answer. A tutorial and sample file can be found at- http://editorconfig.org

README.md: Is information users see at the bottom of a git project. It informs them of the purpose. It is one of the first things they see despite it being it being at the bottom of the page. I have seen this vary from a basic introduction to a full blown documentation.

CONTRIBUTING.md: Provides guidelines everyone contributing to the code needs to follow (primarily developers).

COMMITTER.md: Provides guidelines to anyone with admin-power, like people that can have pull request on Master-branch. This might not be a consider problems in a small project. But it is something to consider in big codebases with core contributors scattered across difference time zones.

ChangeLog.md: A listing of what are changes in every release.

DEVELOPER.md: Instructions potential contributors on how to get the codebase running locally.

Author.txt: Listing of contributors

LICENSE.md or License.txt or License: This expresses to consumers of a code how the creator wants you to use it.  THIS IS IMPORTANT! It is vital for the code creators to write a license and the code consumer to read. If can only remember just one thing from this blog, remember that the license file should be given serious consideration. Some licenses say basically you can use the code but the creator is not liable for damages (MIT.) Some other license say if you use this code, you must open source the code you use it with; which may be your company’s $5 million codebase (like GPL.) Other say you can use the code for free if you do not modify it or contribute modifications to open source; otherwise you must pay the creators (I know MySQL used to have this.) Again, read the license. Ask the creator if you do not see a license.

You can do a web search and find information on licenses. One I like is wikipedia’s comparison- https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses

This list does not cover them all. There are  others like .gitattributes (used for configuring individual folders) and .mailmap (e-mail listing of contributors). Some third-party dependencies uses some like npm uses .npmignore. You can also create one yourself. I personally like to use .Acknowledgement to recognize anyone, codebases or sites that helped me out a lot while working on a project in Github. Some do not end with .md nor are hidden files but seems important like PATENTS in react.js

Advertisements