github.com/sdboyer/gps@v0.16.3/CONTRIBUTING.md (about)

     1  # Contributing to `gps`
     2  
     3  :+1::tada: First, we're thrilled you're thinking about contributing! :tada::+1:
     4  
     5  As a library trying to cover all the bases in Go package management, it's
     6  crucial that we incorporate a broad range of experiences and use cases. There is
     7  a strong, motivating design behind `gps`, but we are always open to discussion
     8  on ways we can improve the library, particularly if it allows `gps` to cover
     9  more of the Go package management possibility space.
    10  
    11  `gps` has no CLA, but we do have a [Code of Conduct](https://github.com/sdboyer/gps/blob/master/CODE_OF_CONDUCT.md). By
    12  participating, you are expected to uphold this code.
    13  
    14  ## How can I contribute?
    15  
    16  It may be best to start by getting a handle on what `gps` actually is. Our
    17  wiki has a [general introduction](https://github.com/sdboyer/gps/wiki/Introduction-to-gps), a
    18  [guide for tool implementors](https://github.com/sdboyer/gps/wiki/gps-for-Implementors), and
    19  a [guide for contributors](https://github.com/sdboyer/gps/wiki/gps-for-contributors).
    20  There's also a [discursive essay](https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527)
    21  that lays out the big-picture goals and considerations driving the `gps` design.
    22  
    23  There are a number of ways to contribute, all highly valuable and deeply
    24  appreciated:
    25  
    26  * **Helping "translate" existing issues:** as `gps` exits its larval stage, it still
    27    has a number of issues that may be incomprehensible to everyone except
    28    @sdboyer. Simply asking clarifying questions on these issues is helpful!
    29  * **Identifying missed use cases:** the loose `gps` rule of thumb is, "if you can do
    30    it in Go, we support it in `gps`." Posting issues about cases we've missed
    31    helps us reach that goal.
    32  * **Writing tests:** in the same vein, `gps` has a [large suite](https://github.com/sdboyer/gps/blob/master/CODE_OF_CONDUCT.md) of solving tests, but
    33    they still only scratch the surface. Writing tests is not only helpful, but is
    34    also a great way to get a feel for how `gps` works.
    35  * **Suggesting enhancements:** `gps` has plenty of missing chunks. Help fill them in!
    36  * **Reporting bugs**: `gps` being a library means this isn't always the easiest.
    37    However, you could always compile the [example](https://github.com/sdboyer/gps/blob/master/example.go), run that against some of
    38    your projects, and report problems you encounter.
    39  * **Building experimental tools with `gps`:** probably the best and fastest ways to
    40    kick the tires!
    41  
    42  `gps` is still beta-ish software. There are plenty of bugs to squash! APIs are
    43  stabilizing, but are still subject to change.
    44  
    45  ## Issues and Pull Requests
    46  
    47  Pull requests are the preferred way to submit changes to 'gps'. Unless the
    48  changes are quite small, pull requests should generally reference an
    49  already-opened issue. Make sure to explain clearly in the body of the PR what
    50  the reasoning behind the change is.
    51  
    52  The changes themselves should generally conform to the following guidelines:
    53  
    54  * Git commit messages should be [well-written](http://chris.beams.io/posts/git-commit/#seven-rules).
    55  * Code should be `gofmt`-ed.
    56  * New or changed logic should be accompanied by tests.
    57  * Maintainable, table-based tests are strongly preferred, even if it means
    58    writing a new testing harness to execute them.
    59  
    60  ## Setting up your development environment
    61  
    62  In order to run `gps`'s tests, you'll need to inflate `gps`'s dependencies using
    63  `glide`. Install `[glide](https://github.com/Masterminds/glide)`, and then download
    64  and install `gps`'s dependencies by running `glide install` from the repo base.
    65  
    66  Also, you'll need to have working copies of `git`, `hg`, and `bzr` to run all of
    67  `gps`'s tests.