Amazing GitHub Template - Sane defaults for your next project!

Overview

Logo

Amazing GitHub Template - Sane defaults for your next project!

Report a Bug · Request a Feature . Ask a Question

license

PRs welcome made with hearth by dec0dOS

Table of Contents

About

Open Source Software is not about the code in the first place but the communications and community. People love good documentation and obvious workflows. If your software solves some problem, but nobody can figure out how to use it or, for example, how to create an effective bug report, there's something very bad going on. Did you hear about Readme Driven Development? Check out the awesome artice written by GitHub co-founder Tom Preston-Werner.

There are many great README or issues templates available on GitHub, however, you have to find them yourself and combine different templates yourself. In addition, if you want extensive docs like CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md or even advanced GitHub features like pull request template, additional labels, code scanning, and automatic issues/PRs closing and locking you have to do much work. Your time should be focused on creating something amazing. You shouldn't be doing the same tasks over and over like creating your GitHub project template from scratch. Follow the don’t repeat yourself principle. So just use the template and go create something amazing!

The key features of Amazing GitHub Template:

  • Configurable README.md template
  • Configurable LICENSE template
  • Configurable CODE_OF_CONDUCT.md template
  • Configurable CONTRIBUTING.md template
  • Configurable SECURITY.md template
  • Configurable issues template
  • Pull request template
  • CODEOWNERS template
  • Additional labels template
  • Automatic locking for closed issues and PRs workflow
  • Automatic cleaning for stale issues and PRs workflow
  • Automatic label verification for PRs workflow
  • Automatic security code scanning workflow via CodeQL
Additional info

This project is the result of huge research. I'm a long-time GitHub user so I've seen more than 7.3k READMEs so far. I've started writing docs for my open source projects (that are currently in their early stages so they exist in the private space for now). After I've analyzed many popular GitHub READMEs and other GitHub-related docs and features I've tried to create a general-propose template that may be useful for any project.

Of course, no template will serve all the projects since your needs may be different. So the Cookiecutter comes to the rescue. It allows Jinja template language to be used for complex cases. Just enter up the project preferences you want in the Cookiecutter interactive menu and that's it. There is a manual setup that could be useful for your existing projects (or if you don't want to use Cookiecutter for some reason). This README.md file is not a template itself, you should download the precompiled template and replace the predefined values, then remove unused sections.

Built With

Getting Started

Prerequisites

The recommended method to install Amazing GitHub Template is by using Cookiecutter. For manual install please refer to manual setup section.

The easiest way to install Cookiecutter is by running:

pip install --user cookiecutter

For other install options, please refer to Cookiecutter installation manual.

Usage

Cookiecutter template

After installing Cookiecutter, all you need to do is to run the following command:

cookiecutter gh:dec0dOS/amazing-github-template

You will get the interactive prompt where you'll need to specify relevant options for your project (or the default value will be used).

Preview

Manual setup

Please follow these steps for manual setup:

  1. Download the precompiled template

  2. Replace all the variables to your desired values

  3. Initialize the repo in the precompiled template folder

    or

    Move the necessary files from precompiled template folder to your existing project directory. Don't forget .github directory that may be hidden by default in your operating system

Variables reference

Please note that entered values are case-sensitive. Default values are provided as an example to help you figure out what should be entered.

On manual setup, you need to replace only values written in uppercase.

Name Default value Description
PROJECT_NAME My Amazing Project Your project name
REPO_SLUG my-amazing-project Repo slug must match the GitHub repo URL slug part
GITHUB_USERNAME dec0dOS Your GitHub username without @
FULL_NAME Alexey Potapov Your full name
OPEN_SOURCE_LICENSE MIT license Full OSS license name
modern_header y Use HTML to prettify your header
table_in_about n Use table to wrap around About section
include_logo y Include Logo section. Could only be used when modern_header == y
include_badges y Include section for badges
include_tos y Include Table of Contents
include_screenshots y Include Screenshots section
include_project_assistance y Include Project assistance section
include_authors y Include Authors & contributors section
include_security y Include Security section and SECURITY.md file
include_acknowledgements y Include Acknowledgements section
include_code_of_conduct y Include CODE_OF_CONDUCT.md file
include_workflows y Include .github/workflows directory
use_codeql y Use CodeQL
use_conventional_commits y Add Conventional Commits notice
use_github_discussions n Use GitHub Discussions

NOTICE: to use GitHub Discussions, you have to enable it first.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please try to create bug reports that are:

  • Reproducible. Include steps to reproduce the problem.
  • Specific. Include as much detail as possible: which version, what environment, etc.
  • Unique. Do not duplicate existing opened issues.
  • Scoped to a Single Bug. One bug per report.

Please adhere to this project's code of conduct.

You could use markdownlint-cli to check for common markdown style inconsistency.

Support

Reach out to the maintainer at one of the following places:

License

This project is licensed under the MIT license. Feel free to edit and distribute this template as you like.

See LICENSE for more information.

Acknowledgements

Thanks for these awesome resources that were used during the development of the Amazing GitHub template:

Comments
  • dev: consider sonia-corporation/stale instead of actions/stale

    dev: consider sonia-corporation/stale instead of actions/stale

    I recently switched from actions/stale to sonia-corporation/stale.

    actions/stale appears to have no further active development, and sonia-corporation/stale has a nice feature: exempting from marking as stale all issues that are in a project (along with issues that are in milestones, or assigned to someone, both of which actions/stale already had). So if people are proposing features, simply accepting them by adding them to a project, like say a version release plan, will keep them from being marked stale without having to add extra labels.

    sonia-corporation/stale also has a much more comprehensive documentation site: https://sonia-corporation.github.io/stale/

    The Yaml keys in the workflow have different names but there's basically a 1:1 correspondence, so it was very fast to update my existing workflow to a new one.

    Anyway just passing this along in case it's helpful!

    enhancement stale 
    opened by rootwork 3
  • Wording suggestions

    Wording suggestions

    Pull request type

    • [ ] Bugfix
    • [ ] Feature
    • [x] Code style update (formatting, renaming)
    • [ ] Refactoring (no functional changes, no api changes)
    • [ ] Build related changes
    • [ ] Documentation content changes
    • [ ] Other (please describe):

    What is the current behavior?

    Nothing is inaccurate, there are just a few places where things are confusing or could be phrased better.

    Note that while this generally touches the template documentation, it's not about this project's documentation, which is why I marked it as "code style update."

    Issue Number: #3

    What is the new behavior?

    I've left inline comments over at https://github.com/dec0dOS/amazing-github-template/pull/6/files (or just scroll down).

    • Typo fixes
    • Grammar fixes
    • Simplification and/or clarification
    • Stylistic changes (feel free to reject these if you disagree)
    • A few larger restructuring sections or additions

    Other information

    If you want references for any of the suggested fixes, let me know.

    opened by rootwork 2
  • feat: Configurable stale/close workflow

    feat: Configurable stale/close workflow

    Feature Request

    Describe the Feature Request

    I think the project should be more transparent about a) including this specific workflow, and b) allowing it to be more easily configurable.

    My projects are mostly pretty small. If I get contributions, I'm willing to give a long time for contributors to respond to feedback, and I might never close an issue, even if it hasn't had activity, in case someone is willing to take it up at some point in the future. (I don't mind issues being closed so much as them being locked to new comments.)

    PR https://github.com/dec0dOS/amazing-github-template/pull/2 is actually a good example. For your project it may make sense to mark it as stale after 30 days, and close it a week later, but for me that would be too quick. I don't have many contributors, and I want to give them more leeway.

    If this is added to an existing project, maintainers might not realize this is one of the workflows being enabled, and/or might not realize the timeline that's now being enforced.

    I realize one can go in and just remove the workflow or change the days-before-stale or days-before-close values, but this is about surfacing something that could be a surprising or disruptive change for a small project.

    Describe Preferred Solution

    1. Assuming you don't want to inquire in the setup process about every single workflow, consider making this one a special case and allowing people to enable/disable it on setup.

    2. If enabled, inquire in the setup what the values of days-before-stale and days-before-close should be.

    3. Note in the project documentation how to remove or change this workflow (and maybe workflows in general) if it isn't important to a project.

    Describe Alternatives

    Just do number 3 above. To me that would be sub-optimal, but better than not mentioning it at all.

    Related Code

    Additional Context

    N/A

    If the feature request is approved, would you be willing to submit a PR? (Help can be provided if you need assistance submitting a PR)

    • [x] Yes
    • [ ] No
    enhancement stale 
    opened by rootwork 2
  • feat: Wording/language cleanup

    feat: Wording/language cleanup

    Feature Request

    Describe the Feature Request

    There is some wording in some places that seems a little clunky or unclear -- I'm not sure if this is a translation issue or something else, but I thought I could offer some suggestions for making things more straightforward.

    Describe Preferred Solution

    Happy to make a PR with suggestions if you're open to it.

    Describe Alternatives

    N/A

    Related Code

    N/A

    Additional Context

    I don't have any, but I could probably find style guides etc. if you want "objective" citations for my opinions on things :)

    If the feature request is approved, would you be willing to submit a PR? Yes / No (Help can be provided if you need assistance submitting a PR)

    enhancement 
    opened by rootwork 2
  • feat: automatic releases

    feat: automatic releases

    • Automatic release on pull_request to main branch
    • Automatic pre-release on push or pull_request on develop branch
    • Updated documentation
    • Updated template project folder
    • Integrated .gitignore on template project folder
    stale 
    opened by devalexanderdaza 2
  • Update pr-labels.yml

    Update pr-labels.yml

    Allows PRs both from the same repository as well as forks. According to: https://github.com/marketplace/actions/verify-pull-request-labels

    Pull request type

    Please check the type of change your PR introduces:

    • [ ] Bugfix
    • [x] Feature
    • [ ] Code style update (formatting, renaming)
    • [ ] Refactoring (no functional changes, no api changes)
    • [ ] Build related changes
    • [ ] Documentation content changes
    • [ ] Other (please describe):

    What is the current behavior?

    • Fails then running PR labels check from the fork.

    Issue Number: N/A

    What is the new behavior?

    • Allows PRs both from the same repository as well as forks

    Other information

    opened by ss-o 1
  • Changed yes/no in feature request template to checkboxes

    Changed yes/no in feature request template to checkboxes

    Under the question "If the feature request is approved, would you be willing to submit a PR?" I changed the response template to checkboxes. This matches the template for PRs (under "Does this introduce a breaking change?")

    Pull request type

    Please check the type of change your PR introduces:

    • [ ] Bugfix
    • [x] Feature
    • [ ] Code style update (formatting, renaming)
    • [ ] Refactoring (no functional changes, no api changes)
    • [ ] Build related changes
    • [ ] Documentation content changes
    • [ ] Other (please describe):

    What is the current behavior?

    Unclear what one is supposed to do when responding to the Yes/No question -- bold the answer? Delete the non-answer? And the italicized help text makes it a little more confusing.

    Issue Number: N/A

    What is the new behavior?

    • plain text => checkboxes

    Other information

    None

    opened by rootwork 1
  • bump v2 to v3 lock.yml

    bump v2 to v3 lock.yml

    Breaking changes: v2 to v3

    input parameter names have changed

    Ref: https://github.com/dessant/lock-threads/blob/08e671be8ac8944d0e132aa71d0ae8ccfb347675/CHANGELOG.md#300-2021-09-27

    Pull request type

    Please check the type of change your PR introduces:

    • [ ] Bugfix
    • [ ] Feature
    • [x] Code style update (formatting, renaming)
    • [ ] Refactoring (no functional changes, no api changes)
    • [ ] Build related changes
    • [ ] Documentation content changes
    • [ ] Other (please describe):

    What is the current behavior?

    Unexpected input(s): 'issue-lock-inactive-days', 'pr-lock-inactive-days'.

    Issue Number: N/A

    What is the new behavior?

    Renamed following input parameters to allow upgrading from v2 to v3:

    • issue-lock-inactive-days --> issue-inactive-days
    • pr-lock-inactive-days --> pr-inactive-days

    Other information

    opened by ss-o 0
Releases(latest)
Owner
Alexey Potapov
null
This project aims to test check if your RegExp are being matched by grep.

Bash RegExp This project aims to test check if your RegExp are being matched by grep. It's a local server that starts on the port 8080. It runs the se

Quatrecentquatre 1 Feb 28, 2022
The project is investigating methods to extract human-marked data from document forms such as surveys and tests.

The project is investigating methods to extract human-marked data from document forms such as surveys and tests. They can read questions, multiple-choice exam papers, and grade.

Harry 5 Mar 27, 2022
This project is a small tool for processing url-containing texts delivered by HUAWEI Share on Windows.

hwshare_helper This project is a small tool for handling url-containing texts delivered by HUAWEI Share on Windows. config Before use, please install

null 1 Jan 19, 2022
Etranslate is a free and unlimited python library for transiting your texts

Etranslate is a free and unlimited python library for transiting your texts

Abolfazl Khalili 16 Sep 13, 2022
Answer some questions and get your brawler csvs ready!

BRAWL-STARS-V11-BRAWLER-MAKER-TOOL Answer some questions and get your brawler csvs ready! HOW TO RUN on android: Install pydroid3 from playstore, and

null 9 Jan 7, 2023
a python package that lets you add custom colors and text formatting to your scripts in a very easy way!

colormate Python script text formatting package What is colormate? colormate is a python library that lets you add text formatting to your scripts, it

Rodrigo 2 Dec 14, 2022
Python tool to make adding to your armory spreadsheet armory less of a pain.

Python tool to make adding to your armory spreadsheet armory slightly less of a pain by creating a CSV to simply copy and paste.

null 1 Oct 20, 2021
Add your new words to a text file and get them randomly.

Memorize-New-Words In this very very very little project, I've wrote a code to memorize new english words. Therefore you can add the words and their m

Mostafa 2 Jul 4, 2022
The app gets your sutitle.srt and proccess it to extract sentences

DubbingAssistants This app gets your sutitle.srt and proccess it to extract sentences, and also find Start time and End time of them. Step 1: install

Ali Booresh 1 Jan 4, 2022
Simple python program to auto credit your code, text, book, whatever!

Credit Simple python program to auto credit your code, text, book, whatever! Setup First change credit_text to whatever text you would like to credit

Hashm 1 Jan 29, 2022
This is an AI that is supposed to say you if your text is formal or not

This is an AI that is supposed to say you if your text is formal or not. It's written in Python 3 and has some german examples (because I'm german yk) in the text.json file. This file contains the text which the AI. The TXT-file isn't important but necessary.

null 1 Jan 12, 2022
Simple DDL Parser to parse SQL (HQL, TSQL, AWS Redshift, Snowflake and other dialects) ddl files to json/python dict with full information about columns: types, defaults, primary keys, etc.

Simple DDL Parser Build with ply (lex & yacc in python). A lot of samples in 'tests/. Is it Stable? Yes, library already has about 5000+ usage per day

Iuliia Volkova 95 Jan 5, 2023
Use CSV files as a Nornir Inventory source with hosts, groups and defaults.

nornir_csv Use CSV files as a Nornir Inventory source with hosts, groups and defaults. This can be used as an equivalent to the Simple Inventory plugi

Matheus Augusto da Silva 2 Aug 13, 2022
sane is a command runner made simple.

sane is a command runner made simple.

Miguel M. 22 Jan 3, 2023
Sane and flexible OpenAPI 3 schema generation for Django REST framework.

drf-spectacular Sane and flexible OpenAPI 3.0 schema generation for Django REST framework. This project has 3 goals: Extract as much schema informatio

T. Franzel 1.4k Jan 8, 2023
Sane color handling of osx's accent and highlight color from the commandline

osx-colors Sane command line color customisation for osx, no more fiddling about with defaults, internal apple color constants and rgb color codes Say

Clint Plummer 8 Nov 17, 2022
NExT-QA: Next Phase of Question-Answering to Explaining Temporal Actions (CVPR2021)

NExT-QA We reproduce some SOTA VideoQA methods to provide benchmark results for our NExT-QA dataset accepted to CVPR2021 (with 1 'Strong Accept' and 2

Junbin Xiao 50 Nov 24, 2022
NExT-Ford-aula4 - NExT Ford aula4

Questão 1: vocês deveram fazer o passo a passo de como ficará as pilhas(Stack) e

Gerson 1 Jan 6, 2022
A Python command-line utility for validating that the outputs of a given Declarative Form Azure Portal UI JSON template map to the input parameters of a given ARM Deployment Template JSON template

A Python command-line utility for validating that the outputs of a given Declarative Form Azure Portal UI JSON template map to the input parameters of a given ARM Deployment Template JSON template

Glenn Musa 1 Feb 3, 2022
A delightful and complete interface to GitHub's amazing API

ghapi A delightful and complete interface to GitHub's amazing API ghapi provides 100% always-updated coverage of the entire GitHub API. Because we aut

fast.ai 428 Jan 8, 2023