github.com/jonsyu1/godel@v0.0.0-20171017211503-64567a0cf169/docs/GitHub-wiki.md (about)

     1  Summary
     2  -------
     3  The `github-wiki` task can be used to sync a particular directory with the GitHub wiki for a project.
     4  
     5  Tutorial start state
     6  --------------------
     7  
     8  * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory
     9  * Project contains `godel` and `godelw`
    10  * Project contains `main.go`
    11  * Project contains `.gitignore` that ignores IDEA files
    12  * Project contains `echo/echo.go`, `echo/echo_test.go` and `echo/echoer.go`
    13  * `godel/config/dist.yml` is configured to build `echgo`
    14  * Project is tagged as 0.0.1
    15  * `godel/config/dist.yml` is configured to create distributions for `echgo`
    16  * Project is tagged as 0.0.2
    17  * Go files have license headers
    18  * `godel/config/generate.yml` is configured to generate string function
    19  * `godel/config/exclude.yml` is configured to ignore all `.+_string.go` files
    20  * `integration_test` contains integration tests
    21  * `godel/config/test.yml` is configured to specify the "integration" tag
    22  
    23  ([Link](https://github.com/nmiyake/echgo/tree/676aad36a5c355af826397be682f49bbb4a9ed20))
    24  
    25  Sync a docs directory with a GitHub wiki
    26  ----------------------------------------
    27  
    28  We will now add documentation for `echgo` and sync it with the GitHub wiki for the project.
    29  
    30  Run the following to create a "docs" directory and add some documentation and commit the changes:
    31  
    32  ```
    33  ➜ mkdir -p docs
    34  ➜ echo '* [Home](https://github.com/nmiyake/echgo/wiki)' > docs/_Sidebar.md
    35  ➜ echo '`echgo` is a tool that echoes the input provided by the user.' > docs/Home.md
    36  ➜ git add docs
    37  ➜ git commit -m "Add documentation"
    38  [master 17c7406] Add documentation
    39   2 files changed, 2 insertions(+)
    40   create mode 100644 docs/Home.md
    41   create mode 100644 docs/_Sidebar.md
    42  ```
    43  
    44  The `github-wiki` task requires a project to have an existing GitHub wiki before it can work. In order to do this, one
    45  needs to be created using the GitHub UI. Navigate to the wiki for the project (for this example, the URL is
    46  https://github.com/nmiyake/echgo/wiki), click on the "Create the first page" button and click on the "Save Page" button
    47  to save the first page with the default content.
    48  
    49  Now that the wiki exists, run the `github-wiki` task to publish the `docs` directory to the GitHub wiki:
    50  
    51  ```
    52  ➜ ./godelw github-wiki --docs-dir docs --repository=git@github.com:nmiyake/echgo.wiki.git
    53  Pushing content of docs to git@github.com:nmiyake/echgo.wiki.git...
    54  ```
    55  
    56  This commits the contents of the `docs` directory to the GitHub wiki repository:
    57  
    58  ![wiki](images/tutorial/githubwiki_page.png)
    59  
    60  Tutorial end state
    61  ------------------
    62  
    63  * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory
    64  * Project contains `godel` and `godelw`
    65  * Project contains `main.go`
    66  * Project contains `.gitignore` that ignores IDEA files
    67  * Project contains `echo/echo.go`, `echo/echo_test.go` and `echo/echoer.go`
    68  * `godel/config/dist.yml` is configured to build `echgo`
    69  * Project is tagged as 0.0.1
    70  * `godel/config/dist.yml` is configured to create distributions for `echgo`
    71  * Project is tagged as 0.0.2
    72  * Go files have license headers
    73  * `godel/config/generate.yml` is configured to generate string function
    74  * `godel/config/exclude.yml` is configured to ignore all `.+_string.go` files
    75  * `integration_test` contains integration tests
    76  * `godel/config/test.yml` is configured to specify the "integration" tag
    77  * `docs` contains documentation
    78  
    79  ([Link](https://github.com/nmiyake/echgo/tree/17c7406291096306e92c6f82da2df09388766693))
    80  
    81  Tutorial next step
    82  ------------------
    83  [Verify project](https://github.com/palantir/godel/wiki/Verify)
    84  
    85  More
    86  ----
    87  
    88  ### Motivation
    89  
    90  GitHub wikis are often a convenient medium for providing documentation for a project. Although GitHub wikis are backed
    91  by a git repository, unlike primary repositories, there is no UI provided for issuing pull requests or conducting code
    92  reviews. Furthermore, because the GitHub wiki repository is separate from a project's primary repository, checking
    93  out only the primary repository does not provide the documentation.
    94  
    95  gödel provides a `github-wiki` task that provides a workflow that addresses all of the above concerns. The `github-wiki`
    96  task can be used to sync the contents of a directory in a project with a GitHub wiki repository. With this mechanism,
    97  documentation changes are done as PRs on the primary repository and the documentation lives in a directory in the
    98  repository. The `github-wiki` task can then be used to push the contents of the documentation directory to the GitHub
    99  wiki, which provides the navigation features offered by GitHub wikis.
   100  
   101  Note that the `github-wiki` task only performs a one-way publish -- any changes that are made to the wiki through the UI
   102  will be overwritten by the `github-wiki` publish task (the `github-wiki` task creates a commit that make the state of
   103  the GitHub wiki mirror the input directory exactly). However, the changes will still exist in the commit history of the
   104  repository, so any content that was added manually or through some other mechanism can be recovered from git history if
   105  necessary.