github.com/kamiazya/dot-github@v1.3.0/README.md (about)

     1  `.github` Directory Generator
     2  =============================
     3  
     4  | Linux and OS X                 | Windows                         | Coverage                         |
     5  | ------------------------------ | ------------------------------- | -------------------------------- |
     6  | [![Travis Badge][]][Travis CI] | [![Appveyor Badge][]][Appveyor] | [![Coverage Badge][]][Coveralls] |
     7  
     8  GitHub now supports [issue and pull request template](https://github.com/blog/2111-issue-and-pull-request-templates).
     9  This repository provides `dot-github` command to generate the template files automatically for your
    10  GitHub repositories.  This also enables to manage template files in dotfiles for all of your machines.
    11  
    12  ![screenshot](https://raw.githubusercontent.com/rhysd/ss/master/dot-github/main.gif)
    13  
    14  ## Getting Started
    15  
    16  ### 1. Installation
    17  
    18  `go get` command
    19  
    20  ```sh
    21  $ go get github.com/rhysd/dot-github
    22  ```
    23  
    24  or [released binaries](https://github.com/rhysd/dot-github/releases)
    25  
    26  ```sh
    27  cd /path/to/Downloads  # Download binary for your platform
    28  chmod +x dot-github_your_platform
    29  mv dot-github_your_platform /usr/local/bin/dot-github
    30  ```
    31  
    32  ### 2. Write Your Template Files
    33  
    34  ```sh
    35  $ mkdir -p ~/.github && cd ~/.github
    36  $ $EDITOR ISSUE_AND_PULL_REQUEST_TEMPLATE.md
    37  $ $EDITOR CONTRIBUTING.md
    38  ```
    39  
    40  Please read below instruction detail about template file
    41  
    42  **Note:** You can change the home directory for `dot-github` by `$DOT_GITHUB_HOME` environment variable.
    43  
    44  ### 3. Generate `.github`
    45  
    46  ```sh
    47  $ cd your-repo
    48  $ dot-github
    49  $ git add .github
    50  ```
    51  
    52  ### 4. Tweak Generated Files
    53  
    54  Tweak generated files in `your-repo/.github/*` for your project-specific information.
    55  
    56  ## Writing Template File
    57  
    58  You can see [example directory in this repository](example/) for real world examples.
    59  
    60  `dot-github` looks below template files
    61  
    62  | File Path                                                     | Description                                                                               |
    63  | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
    64  | `$DOT_GITHUB_HOME/.github/ISSUE_TEMPLATE.md`                  | Template for issues.                                                                      |
    65  | `$DOT_GITHUB_HOME/.github/PULL_REQUEST_TEMPLATE.md`           | Template for pull requests.                                                               |
    66  | `$DOT_GITHUB_HOME/.github/ISSUE_AND_PULL_REQUEST_TEMPLATE.md` | If above files are not found, this file is used for template of issues and pull requests. |
    67  | `$DOT_GITHUB_HOME/.github/CONTRIBUTING.md`                    | Template for contributing guideline.                                                      |
    68  
    69  Note that `$DOT_GITHUB_HOME` is an environment variable.  You can specify your favorite directory to put template files.  Default directory for it is `~`.
    70  
    71  Above template files are parsed as [Golang's standard text template](https://golang.org/pkg/text/template/).  Below variables are available in template.  They are useful to write flexible and common template files for each repositories.
    72  
    73  | Variable Name     | Type      | Description                               |
    74  | ----------------- | --------- | ----------------------------------------- |
    75  | `.IsIssue`        | *boolean* | True when used for issue template.        |
    76  | `.IsPullRequest`  | *boolean* | True when used for pull request template. |
    77  | `.IsContributing` | *boolean* | True when used for contributing template. |
    78  | `.RepoName`       | *string*  | Repository name.                          |
    79  | `.RepoUser`       | *string*  | Repository owner name.                    |
    80  
    81  ## Template Examples
    82  
    83  ### Template files
    84  
    85  - `~/.github/ISSUE_AND_PULL_REQUEST_TEMPLATE.md`
    86  
    87  ```
    88  {{if .IsIssue}}
    89  ### Expected Behavior
    90  
    91  
    92  ### Actual Behavior
    93  
    94  
    95  {{end}}
    96  {{if .IsPullRequest}}
    97  ### Fix or Enhancement?
    98  
    99  
   100  - [ ] All tests passed
   101  {{end}}
   102  
   103  ### Environment
   104  - OS: Write here
   105  - Go version: Write here
   106  ```
   107  
   108  - `~/.github/CONTRIBUTING.md`
   109  
   110  ```
   111  Thank you for contributing {{.RepoName}}!
   112  =========================================
   113  
   114  Please follow issue/PR template.
   115  ```
   116  
   117  ### Generated Files
   118  
   119  - `/path/to/your-repo/.github/ISSUE_TEMPLATE.md`
   120  
   121  ```
   122  ### Expected Behavior
   123  
   124  
   125  ### Actual Behavior
   126  
   127  
   128  ### Environment
   129  - OS: Write here
   130  - Go version: Write here
   131  ```
   132  
   133  - `/path/to/your-repo/.github/PULL_REQUEST_TEMPLATE.md`
   134  
   135  ```
   136  ### Fix or Enhancement?
   137  
   138  
   139  - [ ] All tests passed
   140  
   141  ### Environment
   142  - OS: Write here
   143  - Go version: Write here
   144  ```
   145  
   146  - `/path/to/your-repo/.github/CONTRIBUTING.md`
   147  
   148  ```
   149  Thank you for contributing my-project!
   150  =========================================
   151  
   152  Please follow issue/PR template.
   153  ```
   154  
   155  ## Update `dot-github` command
   156  
   157  To update `dot-github` command, `-selfupdate` flag is recommended.
   158  
   159  ## References
   160  
   161  - [Setting guidelines for repository contributors](https://help.github.com/articles/setting-guidelines-for-repository-contributors/)
   162  - [Creating an issue template for your repository](https://help.github.com/articles/creating-an-issue-template-for-your-repository/)
   163  - [Creating a pull request template for your repository](https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/)
   164  - [Issue と PR のテンプレートジェネレータつくった (Japanese Blog Post)](http://rhysd.hatenablog.com/entry/2016/02/21/233643)
   165  
   166  ## License
   167  
   168  This software is distributed under [MIT license](LICENSE.txt).
   169  
   170  
   171  [Travis Badge]: https://travis-ci.org/rhysd/dot-github.svg?branch=master
   172  [Travis CI]: https://travis-ci.org/rhysd/dot-github
   173  [Appveyor Badge]: https://ci.appveyor.com/api/projects/status/bjat5jyqmcgjfvwd?svg=true
   174  [Appveyor]: https://ci.appveyor.com/project/rhysd/dot-github
   175  [Coverage Badge]: https://coveralls.io/repos/github/rhysd/dot-github/badge.svg?branch=master
   176  [Coveralls]: https://coveralls.io/github/rhysd/dot-github?branch=master