The template README provided on this website is in a form that follows best practices as defined by a number of data editors at social science journals. A full list of endorsers is listed in Endorsers.

Versions

Almost all text on GitHub is processed through a markup language called Markdown — it's an easy way to include simple formatting (like italics, bold words, lists, and links). This guide will show you the ins-and-outs of Markdown on GitHub. 3 minute read Documenting your projects on GitHub. How can I reference (insert a relative link to) an issue in my github Readme.md? I found the following document GitHub Flavored Markdown where it is described how to reference to an issue in a commit, but not in the readme. It looks like that GitHub fetch description meta tag randomly from somewhere in readme.MD, my question is if this can be controlled and defined somehow in readme.MD? I want to define what goes into meta title and meta description and see this in google results.

The most recent version is available at https://social-science-data-editors.github.io/template_README/. Specific releases can be found at https://github.com/social-science-data-editors/template_README/releases.

Formats

The template README is available in a variety of formats:

• HTML (best for reading)

Github Readme Guide 2019

Description

The typical README in social science journals serves the purpose of guiding a reader through the available material and a route to replicating the results in the research paper, including the description of the origins of data and/or description of programs. As such, a good README file should first provide a brief overview of the available material and a brief guide as to how to proceed from beginning to end, before then diving into the specifics.

Data and Code Availability Statement

It contains information about the sources of data used in the replication package, in addition to or instead of such detailed description in the manuscript. This is sometimes referred to as a “Data Availability Statement,” or if it also describes where additional code might be obtained, “Data and Code Availability Statements” (DCAS). A DCAS goes beyond a typical data citation, as it describes additional information necessary for the obtention of the data. These may include required registrations, memberships, application procedures, monetary cost, or other qualifications, beyond a simple URL for download which is typically part of Data Citations.

Computational Requirements

While for simple replication packages, computational requirements may appear to be trivial (a laptop and some common software), this is not always so (expensive commercial software and a super computer cluster). In order to assess the complexity of the task of replicating, authors should specify each of the following elements:

• Software used, including version number as used. If the code is expected to run with a lower version number, that should be added.
• Any additional packages, including their version number or similar, as used.
• The computer hardware specification as used by the author, in terms of OS, CPU generation and quantity, memory and necessary disk space. If multiple computers were used, the specification for each should be identified.
• The wall-clock time given the provided computer hardware, expressed in appropriate units (minutes, days).

Instructions for Data Preparation and Analysis

The README should specify the instructions allowing a replicator to produce the same results. This should include separately instructions for data preparation and for analysis.

We note that a good replication package uses a minimal number of automated scripts, with no manual interventions required unless absolutely unavoidable.

License

The README is under a CC-BY-NC license. Usage by commercial entities is allowed, reselling it is not.

To put your project up on GitHub, you'll need to create a repository for it to live in.

You can store a variety of projects in GitHub repositories, including open source projects. With open source projects, you can share code to make better, more reliable software.

Note: You can create public repositories for an open source project. When creating your public repository, make sure to include a license file that determines how you want your project to be shared with others. For more information on open source, specifically how to create and grow an open source project, we've created Open Source Guides that will help you foster a healthy open source community by recommending best practices for creating and maintaining repositories for your open source project. You can also take a free GitHub Learning Lab course on maintaining open source communities.

1. In the upper-right corner of any page, use the drop-down menu, and select New repository.
2. Type a short, memorable name for your repository. For example, 'hello-world'.
3. Optionally, add a description of your repository. For example, 'My first repository on GitHub.'
4. Choose a repository visibility. For more information, see 'About repository visibility.'
5. Select Initialize this repository with a README.
6. Click Create repository.

Readme Formatting Guide

Congratulations! You've successfully created your first repository, and initialized it with a README file.

Tip: You can also create repositories using the GitHub CLI. For more information, see 'gh repo create' in the GitHub CLI documentation.

Commit your first change

A commit is like a snapshot of all the files in your project at a particular point in time.

When you created your new repository, you initialized it with a README file. README files are a great place to describe your project in more detail, or add some documentation such as how to install or use your project. The contents of your README file are automatically shown on the front page of your repository.

Let's commit a change to the README file.

Github Readme Guide Pdf

1. In your repository's list of files, click README.md.
2. Above the file's content, click .
3. On the Edit file tab, type some information about yourself.
4. Above the new content, click Preview changes.
5. Review the changes you made to the file. You'll see the new content in green.
6. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. You can attribute the commit to more than one author in the commit message. For more information, see 'Creating a commit with multiple co-authors.'
7. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is the default branch, you should choose to create a new branch for your commit and then create a pull request. For more information, see 'Creating a new pull request.'
8. Click Propose file change.

Github Readme Style Guide

Celebrate

Congratulations! You have now created a repository, including a README file, and created your first commit on GitHub. What do you want to do next?

Github Readme Guides

• 'Set up Git'
• Create a repository
• 'Fork a repository'
• 'Be social'
• Connect with people around the world in the GitHub Community Support