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
Posted in Software Development, Uncategorized

Creating a tag in git


This blog post shows you how to create an annotated tag in git; using github. I assume you already have git installed and have at least a working knowledge of the basis.

Steps
Create the tag
git tag -a v1.0.0 -m 'some message'

This is how you push tags to the server (regular push does not move over tags)
git push --tag

Miscellaneous
To view all tags:
git tag -v

To delete a tag (use the view option above to get the tag name )
git tag -d v1.0.0

Posted in Uncategorized

Reminder on how to Perform Basic Git operations on Github-code (using command lines)


This blog is a summary of a way of setting up an environment to use git and checking in code. It assumes you have used a form of source control. If you are a total newbie to programming, try this first – https://try.github.io/levels/1/challenges/1
This blog uses an application called restaurant listing application (https://github.com/ChicagoVeg/restaurantList) for demonstration purposes. Change references to this to suit your needs.

Pre-requisites

  1. Download git: http://git-scm.com/download
  2. Create a repository in github. Go to your github page and click on the Repository-button.

Steps Up Environment

        1. Create a directory on your local drive, where you want the code.
        2. Go to PowerShell or Command Prompt or some other command line application that supports git; and go to the directory from Step #1
        3. In the prompt, type in (to set up directory to be a local git repo):
          git init
        4. Get the code (you will find the URL in the github page, under “HTTPS clone URL”, on the right-hand-side):
          git remote add origin https://github.com/ChicagoVeg/restaurantList.git
        5. Create a master branch
          git checkout -t -b master origin/master
        6. Track changes
          git branch --set-upstream-to=origin/master

Notes

        • If you get an issue where a path name is too long, run this command:
          git config --system core.longpaths true
        • If you get an error where there is no tracking information (means you skipped this step above), run this:
          git branch --set-upstream master origin/master

Checking in Code

      1. Get the code onto your local repo. Reminder, git is about each user having their local repo (for your own changes) and everyone sharing a group-repo (cumulative code one or more people shared)
        git pull
      2. Tracking untracked files (Adding new files to your local repo)
        To untracked files (files not already in github) to the commit package, use this:
        git add .
        Note: This add all untracked files. If you want to add specific files, adjust ths. See this for more more information: https://www.kernel.org/pub/software/scm/git/docs/git-add.html.
      3. Here is a way of committing changes to your local repo:
        git commit -am "This is some comment Fixed #4"Note: (1)This will NOT check in the code to the main repository for others to use. It commits it to your local, which you can later check in for others to use. The push command does the check in and that will be discusses later. (2)This is unnecessary if you have no newly added files. (3)In “-am”, the ‘a’ stands adds all changes while the ‘m’ is for commenting. This is not appropriate if you do not want to add all recent changes to your local repository. Use a different option for commit as suites your needs. (4)The “#4” in the commit associated the check-in to an issue number. It can be left out the comment if you are not associating the commit to an issue. Although I advise to always associate check-ins to something.
      4. To submit code from your local repo to the shared repo, use this command:
        git push
        Note: This pulls from your local repository and pushed it to github.

A tutorial with less verbose than this can be found here: http://davidgiard.com/2016/01/30/MyCommonGitCommands.aspx