From 40025c6214ae36b7bf7fd57ffc37104078875caf Mon Sep 17 00:00:00 2001 From: Justin Hartman Date: Thu, 10 May 2018 22:43:44 +0200 Subject: [PATCH] :rocket: Ready to release version 1.0.0 with these final changes. --- .github/ISSUE_TEMPLATE/BUG_REPORT.md | 2 +- .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md | 8 +- CHANGELOG.md | 12 ++ CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 24 +-- README.md | 184 ++++++++++++++++-- .../.github/ISSUE_TEMPLATE/BUG_REPORT.md | 2 +- .../.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md | 8 +- templates/_basic/CHANGELOG.md | 8 +- templates/_basic/CODE_OF_CONDUCT.md | 2 +- templates/_basic/CONTRIBUTING.md | 24 +-- templates/_basic/README.md | 21 +- 12 files changed, 230 insertions(+), 67 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md index aaa63ee..48a1571 100644 --- a/.github/ISSUE_TEMPLATE/BUG_REPORT.md +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -44,7 +44,7 @@ _If applicable, add screenshots to help explain your problem._ ### Additional Context -Add any other context about the problem here. +_Add any other context about the problem here._ [//]: # (Add links to any screenshots or other relevant information below) diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md index 9383f59..e35d734 100644 --- a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md +++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -5,16 +5,16 @@ about: Suggest an idea or feature for this project. ### Is your feature request related to a problem? Please describe. -A clear and concise description of what the problem is. e.g. _I'm always frustrated when [...]_ +_A clear and concise description of what the problem is. e.g. I'm always frustrated when [...]_ ### Describe the solution you'd like -A clear and concise description of what you want to happen. +_A clear and concise description of what you want to happen._ ### Describe alternatives you've considered -A clear and concise description of any alternative solutions or features you've considered. +_A clear and concise description of any alternative solutions or features you've considered._ ### Additional Context -Add any other context or screenshots about the feature request here. +_Add any other context or screenshots about the feature request here._ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..66cd2f0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +# Project Change-Log + +Below is a detailed change-log, along with specific tasks completed, for each +version released to date. + +## Version 1.0.0 +### 10/05/2018 + +- [#new](#new) + + Initial Release +- [#enhancement](#enhancement) +- [#bugfix](#bugfix) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 95f6b58..0a0b188 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -81,7 +81,7 @@ members of the project's leadership. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at -[http://contributor-covenant.org/version/1/4][version] +[http://contributor-covenant.org/version/1/4][version]. [//]: # (Make sure to change the email address below to your) [//]: # (project-specific email.) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ad5793..42dba80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,29 +2,29 @@ ## Did You Find a Bug? - - **Ensure the bug was not already reported** by searching on GitHub under - [Issues][issues]. - - If you're unable to find an open issue addressing the problem, - [open a new one][new-issue]. Be sure to include a **title and clear - description**, as much relevant information as possible, and a **code - sample** or an **executable test case** demonstrating the expected - behaviour that is not occurring. +- **Ensure the bug was not already reported** by searching on GitHub under + [Issues][issues]. +- If you're unable to find an open issue addressing the problem, + [open a new one][new-issue]. Be sure to include a **title and clear + description**, as much relevant information as possible, and a **code + sample** or an **executable test case** demonstrating the expected + behaviour that is not occurring. ## Did You Write a Patch That Fixes a Bug? - - Open a new GitHub pull request with the patch. +- Open a new GitHub pull request with the patch. + Fork this project + Create your feature branch: `git checkout -b my-new-feature` + Commit your changes: `git commit -am 'Add some feature'` + Push to the branch: `git push origin my-new-feature` + Submit a pull request :tada: - - Ensure the PR description clearly describes the problem and solution. - Include the relevant issue number if applicable. +- Ensure the PR description clearly describes the problem and solution. + Include the relevant issue number if applicable. ## Do You Intend to Add a New Feature or Change an Existing One? - - Suggest your change as a [new issue][new-issue] using the label - `enhancement`, **BEFORE** you start writing code. +- Suggest your change as a [new issue][new-issue] using the label + `enhancement`, **BEFORE** you start writing code. Thanks for contributing! :heart: diff --git a/README.md b/README.md index e15e109..35d592c 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,25 @@ configuration. - [Overview](#overview) -- [Installing](#installing) - [Screenshots](#screenshots) - - [Github Issues](#github-issues) - - [Github Issue - General Report](#github-issue---general-report) - - [Github Issue - Feature Request](#github-issue---feature-request) - - [Github Issue - Bug Report](#github-issue---bug-report) - - [Github Pull Request](#github-pull-request) + - [Github Issues](#github-issues) + - [Github Issue - General Report](#github-issue---general-report) + - [Github Issue - Feature Request](#github-issue---feature-request) + - [Github Issue - Bug Report](#github-issue---bug-report) + - [Github Pull Request](#github-pull-request) +- [Installing](#installing) + - [Clone the repository to your machine](#clone-the-repository-to-your-machine) + - [Copying the main project structure](#copying-the-main-project-structure) + - [Copying only some of the project structure](#copying-only-some-of-the-project-structure) + - [Choosing and Copying a License file](#choosing-and-copying-a-license-file) + - [The Final Structure](#the-final-structure) + - [File Changes](#file-changes) - [Authors](#authors) - [License](#license) - [Contributing](#contributing) - [Code of Conduct](#code-of-conduct) - [Versioning](#versioning) +- [Change-Log](#change-log) - [Acknowledgements](#acknowledgements) @@ -30,16 +37,17 @@ 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][screenshots] for how these - integrate with Github. + 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 very basic and can be tailored to your needs. +- `README.md` file which is thorough and can be tailored to your needs. - `_licenses/` folder containing all available open-source licenses. -This is the full file breakdown of the `/templates/` folder. +This is the full file list of the `/templates/` folder. -```terminal +```console templates/ ├── _basic/ │   ├── .github/ @@ -49,6 +57,7 @@ templates/ │   │   │   └── FEATURE_REQUEST.md │   │   └── PULL_REQUEST_TEMPLATE.md │   ├── .gitignore +│   ├── CHANGELOG.md │   ├── CODE_OF_CONDUCT.md │   ├── CONTRIBUTING.md │   └── README.md @@ -89,10 +98,13 @@ templates/ └── zlib.txt ``` -## Installing - ## 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 Issues][screen-1] @@ -113,6 +125,140 @@ templates/ ![Pull Request][screen-5] +## 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 console. + +```console +$ git clone https://github.com/justinhartman/.github github-templates +$ cd github-templates/ +``` + +**NB:** 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. + +```console +$ cd templates/ +$ cp -R _basic/* /path/to/your/project/folder/ # change path to your project +``` + +This will copy all the files from the `_basic/` folder into your project root +folder. Your project will now contain the following files: + +```console +/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 `_basic/` 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. + +```console +$ cd templates/_basic/ +$ 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. + +```console +$ 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 console. + +```console +$ 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: + +```console +/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][author-1] @@ -141,14 +287,14 @@ along with this program. If not, see . ## Contributing -Please read our [CONTRIBUTING.md][CONTRIBUTING] file for details on how you +Please read the [CONTRIBUTING.md][CONTRIBUTING] file for details on how you can get involved in the project as well as the process for submitting bugs -and pull requests to us. +and pull requests. ## Code of Conduct -Please read our [CODE_OF_CONDUCT.md][COC] file for the guidelines that govern -our community. +Please read the [CODE_OF_CONDUCT.md][COC] file for the guidelines that govern +the community. ## Versioning @@ -156,6 +302,11 @@ We use [Semantic Versioning][semver] for software versions of this project. For a list of all the versions available, see the [tags][tags] and [releases][releases] on this repository. +## Change-Log + +View the [`CHANGELOG.md`][changelog] 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 @@ -190,4 +341,5 @@ some way to make this project a reality. [screen-4]: https://ws4.sinaimg.cn/large/006tKfTcgy1fr6nrhrn19j30lm136jut.jpg [screen-5]: https://ws1.sinaimg.cn/large/006tKfTcgy1fr6nrov8hbj30lg0vlq5o.jpg [daniellmb]: https://github.com/daniellmb/.github +[changelog]: CHANGELOG.md diff --git a/templates/_basic/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/templates/_basic/.github/ISSUE_TEMPLATE/BUG_REPORT.md index aaa63ee..48a1571 100644 --- a/templates/_basic/.github/ISSUE_TEMPLATE/BUG_REPORT.md +++ b/templates/_basic/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -44,7 +44,7 @@ _If applicable, add screenshots to help explain your problem._ ### Additional Context -Add any other context about the problem here. +_Add any other context about the problem here._ [//]: # (Add links to any screenshots or other relevant information below) diff --git a/templates/_basic/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/templates/_basic/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md index 9383f59..e35d734 100644 --- a/templates/_basic/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md +++ b/templates/_basic/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -5,16 +5,16 @@ about: Suggest an idea or feature for this project. ### Is your feature request related to a problem? Please describe. -A clear and concise description of what the problem is. e.g. _I'm always frustrated when [...]_ +_A clear and concise description of what the problem is. e.g. I'm always frustrated when [...]_ ### Describe the solution you'd like -A clear and concise description of what you want to happen. +_A clear and concise description of what you want to happen._ ### Describe alternatives you've considered -A clear and concise description of any alternative solutions or features you've considered. +_A clear and concise description of any alternative solutions or features you've considered._ ### Additional Context -Add any other context or screenshots about the feature request here. +_Add any other context or screenshots about the feature request here._ diff --git a/templates/_basic/CHANGELOG.md b/templates/_basic/CHANGELOG.md index 9ebb271..62b454a 100644 --- a/templates/_basic/CHANGELOG.md +++ b/templates/_basic/CHANGELOG.md @@ -6,7 +6,7 @@ version released to date. ## Version 0.0.1 ### ??/??/2018 - - [#new](#new) - + Initial Commit - - [#enhancement](#enhancement) - - [#bugfix](#bugfix) +- [#new](#new) + + Initial Release +- [#enhancement](#enhancement) +- [#bugfix](#bugfix) diff --git a/templates/_basic/CODE_OF_CONDUCT.md b/templates/_basic/CODE_OF_CONDUCT.md index 87d3c03..bebf6ea 100644 --- a/templates/_basic/CODE_OF_CONDUCT.md +++ b/templates/_basic/CODE_OF_CONDUCT.md @@ -78,7 +78,7 @@ members of the project's leadership. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at -[http://contributor-covenant.org/version/1/4][version] +[http://contributor-covenant.org/version/1/4][version]. [//]: # (Make sure to change the email address below to your) [//]: # (project-specific email.) diff --git a/templates/_basic/CONTRIBUTING.md b/templates/_basic/CONTRIBUTING.md index 0ad5793..42dba80 100644 --- a/templates/_basic/CONTRIBUTING.md +++ b/templates/_basic/CONTRIBUTING.md @@ -2,29 +2,29 @@ ## Did You Find a Bug? - - **Ensure the bug was not already reported** by searching on GitHub under - [Issues][issues]. - - If you're unable to find an open issue addressing the problem, - [open a new one][new-issue]. Be sure to include a **title and clear - description**, as much relevant information as possible, and a **code - sample** or an **executable test case** demonstrating the expected - behaviour that is not occurring. +- **Ensure the bug was not already reported** by searching on GitHub under + [Issues][issues]. +- If you're unable to find an open issue addressing the problem, + [open a new one][new-issue]. Be sure to include a **title and clear + description**, as much relevant information as possible, and a **code + sample** or an **executable test case** demonstrating the expected + behaviour that is not occurring. ## Did You Write a Patch That Fixes a Bug? - - Open a new GitHub pull request with the patch. +- Open a new GitHub pull request with the patch. + Fork this project + Create your feature branch: `git checkout -b my-new-feature` + Commit your changes: `git commit -am 'Add some feature'` + Push to the branch: `git push origin my-new-feature` + Submit a pull request :tada: - - Ensure the PR description clearly describes the problem and solution. - Include the relevant issue number if applicable. +- Ensure the PR description clearly describes the problem and solution. + Include the relevant issue number if applicable. ## Do You Intend to Add a New Feature or Change an Existing One? - - Suggest your change as a [new issue][new-issue] using the label - `enhancement`, **BEFORE** you start writing code. +- Suggest your change as a [new issue][new-issue] using the label + `enhancement`, **BEFORE** you start writing code. Thanks for contributing! :heart: diff --git a/templates/_basic/README.md b/templates/_basic/README.md index ace377d..c57bcdf 100644 --- a/templates/_basic/README.md +++ b/templates/_basic/README.md @@ -5,10 +5,10 @@ _One Paragraph of the project description goes here._ ## Table of Contents - [Getting Started](#getting-started) - - [Prerequisites](#prerequisites) - - [Installing](#installing) + - [Prerequisites](#prerequisites) + - [Installing](#installing) - [Running the tests](#running-the-tests) - - [Break down into end-to-end tests](#break-down-into-end-to-end-tests) + - [Break down into end-to-end tests](#break-down-into-end-to-end-tests) - [Deployment](#deployment) - [Built With](#built-with) - [Contributing](#contributing) @@ -75,14 +75,14 @@ _Add additional notes about how to deploy this on a live system._ ## Contributing -Please read our [CONTRIBUTING.md][CONTRIBUTING] file for details on how you -can get involved in the project as well as the process for submitting bugs and -pull requests to us. +Please read the [CONTRIBUTING.md][CONTRIBUTING] 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 our [CODE_OF_CONDUCT.md][COC] file for the guidelines that govern -our community. +Please read the [CODE_OF_CONDUCT.md][COC] file for the guidelines that govern +the community. ## Versioning @@ -92,7 +92,7 @@ For a list of all the versions available, see the [tags][tags] and ## Change-Log -View [our `CHANGELOG.md`][changelog] file for a detailed list of changes, +View the [`CHANGELOG.md`][changelog] file for a detailed list of changes, along with specific tasks completed for each version released to date. ## Authors @@ -118,8 +118,7 @@ some way to make this project a reality. [//]: # (Make sure to change the URL links for `[tags]`, `[releases]`,) -[//]: # (`[contribs]` and `[author-1]` below to your specific project) -[//]: # (and authors.) +[//]: # (`[contribs]` and `[author-1]` below to your specific project.) [deploy]: #deployment [CONTRIBUTING]: CONTRIBUTING.md