.github

A set of Github templates that accelerate your project setup and
configuration.

Overview
Screenshots
Installing
Authors
License
Contributing
Code of Conduct
Versioning
Change-Log
Acknowledgements

Overview

Everything you need is contained within the /templates/ folder. This
includes all the files needed to start a project from scratch, which include:

.github/ folder with templates for working with Github's Issue and
Pull Request. See the screenshots below for how these
integrate directly with Github.
.gitignore file to ignore certain files and folders.
CHANGELOG.md file provides a template for tracking releases and changes.
CODE_OF_CONDUCT.md file which governs your project.
CONTRIBUTING.md file outlining how contributors can get involved.
README.md file which is thorough and can be tailored to your needs.
_licenses/ folder containing all available open-source licenses.

The below output is the full file list of the /templates/ folder.

templates/
├── _core/
│   ├── .github/
│   │   ├── ISSUE_TEMPLATE/
│   │   │   ├── BUG_REPORT.md
│   │   │   ├── CUSTOM.md
│   │   │   └── FEATURE_REQUEST.md
│   │   └── PULL_REQUEST_TEMPLATE.md
│   ├── .gitignore
│   ├── CHANGELOG.md
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTRIBUTING.md
│   └── README.md
└── _licenses/
    ├── afl-3.0.txt
    ├── agpl-3.0.txt
    ├── apache-2.0.txt
    ├── artistic-2.0.txt
    ├── bsd-2-clause.txt
    ├── bsd-3-clause-clear.txt
    ├── bsd-3-clause.txt
    ├── bsl-1.0.txt
    ├── cc-by-4.0.txt
    ├── cc-by-sa-4.0.txt
    ├── cc0-1.0.txt
    ├── ecl-2.0.txt
    ├── epl-1.0.txt
    ├── epl-2.0.txt
    ├── eupl-1.1.txt
    ├── eupl-1.2.txt
    ├── gpl-2.0.txt
    ├── gpl-3.0.txt
    ├── isc.txt
    ├── lgpl-2.1.txt
    ├── lgpl-3.0.txt
    ├── lppl-1.3c.txt
    ├── mit.txt
    ├── mpl-2.0.txt
    ├── ms-pl.txt
    ├── ms-rl.txt
    ├── ncsa.txt
    ├── ofl-1.1.txt
    ├── osl-3.0.txt
    ├── postgresql.txt
    ├── unlicense.txt
    ├── upl-1.0.txt
    ├── wtfpl.txt
    └── zlib.txt

Screenshots

The screenshots below demonstrate how the files contained in the .github/
folder integrate with Github's Issue and Pull Request features. As you
will see, each template allows you to have a unique template when logging
Issues or creating a Pull Request.

Github Issues

Github Issue - General Report

Github Issue - Feature Request

Github Issue - Bug Report

Github Pull Request

Installing

Clone the repository to your machine

First off you want to clone the repository to your local machine. You can do
so by running the following commands in a terminal.

$ git clone https://gitlab.com/justinhartman/github-templates github-templates
$ cd github-templates/

If you're checking out the code from GitHub please note that specifying a
name for the checkout folder (e.g. github-templates) when running git clone
is very important. If you don't, git will checkout the repo to a folder called
.github on your local machine. If you are using macOS or Linux you won't
be able to see the newly checked out repo due to the fact it begins with a
period (.) and will be hidden by the file-system. It is there; you just cannot
see it without running something like ls -la.

Copying the main project structure

To copy the main project structure for a new project simply execute the
following commands from the repository root folder.

$ cd templates/
$ cp -R _core/ /path/to/your/project/folder/ # change path to your project

This will copy all the files from the _core/ folder into your project root
folder. Your project will now contain the following files:

/path/to/your/project/folder/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── BUG_REPORT.md
│   │   ├── CUSTOM.md
│   │   └── FEATURE_REQUEST.md
│   └── PULL_REQUEST_TEMPLATE.md
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
└── README.md

Copying only some of the project structure

You may not want to copy everything contained in the _core/ folder;
especially if you've already initiated a git repo (i.e. git init) and have
a .gitignore and/or README.md file already contained in your project path.

Copying only some of the main project structure files can be achieved by
running the following commands.

$ cd templates/_core/
$ cp -R .github .gitignore CHANGELOG.md CODE_OF_CONDUCT.md \
   CONTRIBUTING.md README.md \
     /path/to/your/project/folder/ # change path to your project

You can simply remove the file(s) and/or .github folder from the above cp
command thereby copying only the files/folder you need. For example, the below
will copy everything except the README.md and .gitignore files.

$ cp -R .github CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md \
  /path/to/your/project/folder/ # change path to your project

Choosing and Copying a License file

The _licenses folder contains a collection of largely most of the
open-source licenses available. To copy a license, choose one from the folder
and run the following from your terminal.

$ cd templates/_licenses/
$ cp mit.txt /path/to/your/project/folder/LICENSE # change path to your project
                                                  # but leave LICENSE intact

NB: make sure that when you copy a license file you always name your
license as LICENSE and not, for example, mit.txt. Github looks for a file
called LICENSE in the root of your project folder so anything other than
this and Github won't be able to figure out what license your project is
under.

The Final Structure

Once you have copied across the basic project structure and a license file you
should end up with your project directory looking like this:

/path/to/your/project/folder/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── BUG_REPORT.md
│   │   ├── CUSTOM.md
│   │   └── FEATURE_REQUEST.md
│   └── PULL_REQUEST_TEMPLATE.md
├── .gitignore
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md

File Changes

These templates have been designed to work out-the-box without much need for
intervention on your part. There are however a few files where you will need
to make some changes in order to tailor this to your project. See below for a
list of changes you should make before committing to your repo.

As a recommendation, it is better to edit the files in your project folder
rather than in this repository. This will allow you to update the repo without
losing any changes you may have made.

/.gitignore - this template has been configured to ignore file-system
specific files for macOS, Windows and Linux. Delete whatever is not
relevant to your needs.
/CHANGELOG.md - update your versioning structure and enter a release date.
/README.md - you will make many changes to this file but you must update
the URLs at the end of the file. Currently they link to this repo and should
be replaced with your Github project URL.
/CONTRIBUTING.md - as with the README.md you need to update the links
to your project at the end of the file.
/CODE_OF_CONDUCT.md - at the end of this file you will need to replace the
generic email address with an email address for your project.

Authors

Justin Hartman - @justinhartman

Also see the list of contributors who have participated in this
project.

License

This project is licensed under the AGPL-3.0 License. See the
LICENSE file for full details.

Copyright (C) 2018 Justin Hartman <justin@hartman.me>.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

Contributing

Please read the CONTRIBUTING.md file for details on how you
can get involved in the project as well as the process for submitting bugs
and pull requests.

Code of Conduct

Please read the CODE_OF_CONDUCT.md file for the guidelines that govern
the community.

Versioning

We use Semantic Versioning for software versions of this project.
For a list of all the versions available, see the tags and
releases on this repository.

Change-Log

View the CHANGELOG.md file for a detailed list of changes,
along with specific tasks completed for each version released to date.

Acknowledgements

Special thanks go out to the following people and projects who have helped in
some way to make this project a reality.

@daniellmb/.github - for the original idea to create a
.github template pack.
PurpleBooth/README-Template.md - for the README file
inspiration.
Github - for the ISSUE_TEMPLATE template files.

justinhartman/.github