From 7b628847f1940b34d3f4b20803fb61e9875ae80e Mon Sep 17 00:00:00 2001 From: Steven L Date: Tue, 3 Oct 2017 12:24:10 -0400 Subject: [PATCH] Created Contributing to ssh-chat (markdown) --- Contributing-to-ssh-chat.md | 89 +++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 Contributing-to-ssh-chat.md diff --git a/Contributing-to-ssh-chat.md b/Contributing-to-ssh-chat.md new file mode 100644 index 0000000..766e8a9 --- /dev/null +++ b/Contributing-to-ssh-chat.md @@ -0,0 +1,89 @@ +If you want to contribute to `ssh-chat`, it is very easy to do so. It's recommended to check the open issues section first to see what issues are open currently. Bugfixes will be prioritized and typically included in the next release of `ssh-chat`. + +## Contribution Guidelines + +Contributing to `ssh-chat` can be done through many different ways; looking for bugs and reporting them in issues, reproducing bugs and contributing to existing issues, editing the wiki for mistakes or adding any information that was previously missing, bug fixes in the source code, new feature implementations for `ssh-chat`, or improving the test cases. + +### Issues + +Issues are for bug reports or feature requests. We ask that if an issue you wanted to submit was already submitted, you simply vote with the emojis instead of smaller, repetitive comments like "+1" or "I agree". If there is a feature you want to see implemented, use the thumbs up emoji. + +### Wiki Editing + +The Wiki is reserved for explaining things in greater detail when the source code comments or README fails to provide enough information. If you found something confusing like how to set up `ssh-chat`, you can submit an issue for more information to be provided and someone can create a Wiki page to help you, and in turn, this will help future confusion for others. + +If you found the grammar or wording confusing on any wiki page, you can also feel free to edit anything. + +### Golang and Formatting + +`ssh-chat` is built using Google's Golang (or Go for short). `ssh-chat` works on many platforms, see the [release page](https://github.com/shazow/ssh-chat/releases) for all available downloads. + +The source code for `ssh-chat` currently uses the `gofmt` style of coding. All code must be formatted with `gofmt`, otherwise the program will fail to build correctly. For more information on `gofmt`, [see here](https://golang.org/cmd/gofmt/). + +For text editors that support Golang, there are many different editors that you can use with varying Golang support: +* (Neo)Vim with Golang syntax plugins ([Syntastic](https://github.com/vim-syntastic/syntastic) or [Vim-Go](https://github.com/fatih/vim-go)) +* Emacs with [a Golang major mode](https://github.com/dominikh/go-mode.el) +* Visual Studio Code using the [vscode-go](https://github.com/Microsoft/vscode-go) plugin +* Sublime Text 3 with [GoSublime](https://github.com/DisposaBoy/GoSublime) +* Atom using [go-plus](https://atom.io/packages/go-plus) + +### Cloning and Building ssh-chat + +In order to build `ssh-chat`, you will need a recent version of the Golang compiler. Anything above version 1.5 should work just fine. If `ssh-chat` makes use of any recently released features, the requirements will change. + +In order to build `ssh-chat`, Golang has to pull in dependencies from listed sources and pull them into one big workspace, called the `$GOPATH`. The first thing to do is configure your `$GOPATH` environment variable, and use the `get` comment in Golang to fetch the `ssh-chat` code repository and all of it's dependencies. + +```bash +$ export GOPATH=$HOME/go # Add this to your ~/.bashrc or similar +$ go get -u github.com/shazow/ssh-chat +$ cd $GOPATH/src/github.com/shazow/ssh-chat +$ make +``` + +For more information on how Go builds projects, check this article: [How to Write Go Code](https://golang.org/doc/code.html). + +### Forking and Pull Requests + +If you are unfamiliar with Go, or maybe you have experience writing C/C++ or Java, you should check out these sites to learn some Golang. + +* [A Tour of Golang](https://tour.golang.org/) +* [Go By Example](https://gobyexample.com/) + +For contributions to `ssh-chat` source code, `ssh-chat` uses the [GitFlow branching model](http://nvie.com/posts/a-successful-git-branching-model/) for contribution. New features and bugfixes are done on separate branches from the `master` branch, and pull requests will merge those branches into the `master` branch. When enough features and fixes are applied to the `master` branch, `ssh-chat` will be tagged for a new release. + +In order to contribute to `ssh-chat`, you must create a forked repository by clicking "fork" at the top-right part of the page. This will create a repository under your account with all of `ssh-chat`'s source code. From here you can run `go get -u github.com/username/ssh-chat` and do all of the previously mentioned steps for building, but you can actually skip this part by using the original repository and setting up an additional remote location from it. + +```bash +$ export GOPATH=$HOME/go # steps from before +$ go get -u github.com/shazow/ssh-chat +$ cd $GOPATH/src/github.com/shazow/ssh-chat +$ git remote add myrepo https://github.com/my-username/ssh-chat # add your fork URL here +$ git checkout -b my-new-cool-feature # switch to a new branch to start working on code +``` + +Now after switching to a new branch, you can start adding new features or bugfixing right away and committing. Once you make some changes, you can stage the changes, commit the changes, and push the changes to your forked repository. + +```bash +$ git status # check to see your changes +$ git add -A # add everything (or add individual files with "git add path/to/file") +$ git commit -m "My cool new feature or bugfix" # commit with a message +$ git push -u myrepo # push the changes to your forked repository +``` + +Once you upload your changes, you can then submit a Pull Request to the original repository for review. If it passes the code review, and the changes pass the Continuous Integration tests on Travis, your changes will be added to the `ssh-chat` codebase! + +### Testing Code Locally + +Before uploading changes, you should always test them locally to make sure they are working how you envisioned them. The best way is to start a local `ssh-chat` server and connect a few clients to it. + +```bash +$ cd $GOPATH/src/github.com/shazow/ssh-chat # cd to the project +$ make # build the project +$ ./ssh-chat + +# in another terminal do +$ ssh -p 2022 username@localhost +``` + +Test your changes here, whether it's client commands, private messages, switching rooms, moderation actions, themes, or something related to public key fingerprints. +