README has been an established convention in software development since at least the 1960s, when I saw my first one printed out IN ALL CAPS on the green-and-white paper that was wrapping a stack of Hollerith cards intended to be run on an IBM 1640. I saw many more in the 1970s, on every conceivable media and operating system, when I worked on DEC minicomputers and large IBM mainframes. See also REAMDE.
Git/GitHub tip No. 19: Use Markdown
Early README files IN ALL CAPS were more than a little basic. The current standard for formatting README files is Markdown, specifically GitHub Flavored Markdown. I used to see README files in HTML, but the practice seems to be fading.
Git/GitHub tip No. 20: Convert your older repos to Git
Of all the tips I’ve listed, this one might be the hardest to implement, both technically and politically. Politically it’s hard because programmers are by nature conservative about their tools. That needs to be addressed with training (see tip No. 5).
It’s technically hard to convert big, old repositories with millions of lines of code, tens of thousands of commits, and thousands of tags because the processes for this use a metric ton of memory. I have had decade-old CVS repositories that would only convert on large or extralarge Amazon EC2 instances, and they still took days for the conversion to complete. If you’re converting from Subversion, try using svn2git. If you’re converting from CVS, consider git -cvsimport and cvs2git.
Git/GitHub tip No. 21: Use GitHub project boards
GitHub project boards, which can belong to a user, organization, or repository, contain cards organized into columns. The cards may be issues (see tip No. 17), pull requests (see tip No. 16), or notes; the columns may be anything that is useful to the project. For example, the TensorFlow PR queue contains issue cards in columns classifying the issue status: assigned reviewer, changes requested, approved, merged, and closed/rejected.
Git/GitHub tip No. 22: Automate your workflow with GitHub Actions
GitHub Actions allow you to create workflows, such as continuous integration (CI) and continuous deployment (CD), that are triggered by GitHub events such as code pushes, pull requests, and issue creation. Actions may be used instead of separate automation servers such as Jenkins.
Git/GitHub tip No. 23: Build and publish packages
GitHub Packages is a software package hosting service for NPM, Docker, Maven, Gradle, NuGet, and RubyGems. A GitHub package inherits its permissions from the repository to which it belongs. You can integrate GitHub Packages with GitHub APIs, GitHub Actions (see tip No. 22), and webhooks. You can install packages as dependencies in your projects, and you can publish packages for use by anyone authorized to access the repository.
Git/GitHub tip No. 24: Check and resolve your security advisories and alerts
Every repository on GitHub has a security tab that lists the repo’s security alerts, advisories, and policy. GitHub sends security alerts when it detects vulnerabilities affecting your repository. A vulnerability is a problem in a project’s code that could be exploited to damage the confidentiality, integrity, or availability of the project or other projects that use its code.
Advisories are drafts where you can privately discuss, fix, and publish information about security vulnerabilities in your repository’s code. A security policy communicates how your community can securely report security vulnerabilities for your project. GitHub monitors your project dependencies and automatically opens pull requests to update dependencies to the minimum version that resolves known vulnerabilities.
Git/GitHub tip No. 25: Scan your code for vulnerabilities
In addition to acting on security alerts, you should also scan your code for vulnerabilities. Semmle’s semantic code analysis engine, CodeQL, treats code as data. In addition to running CodeQL directly on your repositories, you can run it from IDEs such as Visual Studio Code and CI/CD services.
Git/GitHub tip No. 26: Publish your documentation pages
GitHub Pages is designed to host your personal, organization, or project web pages from a GitHub repository, in a blog-like way. To enable Pages for a repository, go to the settings for the repository, scroll down to the GitHub Pages section, and choose either a branch or the /docs folder of the master branch.
You can also choose a Jekyll theme for your pages. Note that because GitHub Pages supports the Jekyll static site generator, you can write your documentation in plain text or Markdown; in other words, you don’t need to write HTML, although you can use HTML if you wish. You can also use a custom domain for a GitHub Pages site simply by adding a CNAME file from your repo settings and adding a CNAME record to your domain settings at your DNS provider.
You get one site per GitHub account and organization, and unlimited project sites. To create a site for your account, create a new repository named <username>.github.io, where <username> is your GitHub user or organization name. Then start committing content to that repo.
Git/GitHub tip No. 27: Collaborate on documentation in wikis
Every GitHub repository can contain a wiki, which is intended to host documentation, examples, support, and mission statements beyond the high-level description in the standard README.md file. By default, only people with write access to your repository can make changes to wikis, although you can allow everyone on GitHub to contribute to a wiki in a public repository. You can enable or disable wikis for a repo in the Features section of the settings page, and you can optionally restrict editing to repository collaborators.
Git and GitHub resources
- GitHub
- Pro Git book
- Git—the simple guide
- GitHub help
- Get Started with Git
- GitHub for Beginners
- Git Immersion
- Git Community Book
- Git from the bottom up [PDF]
- Git Magic
- A Visual Git Reference
- Atlassian Git Tutorials