CONTRIBUTING.md

How to Contribute

This project is based on GitHub and can be accessed by clicking here.

Here are the basic of contributing to GitHub:

1. Fork and clone the project
2. Set up the project locally
3. Create an upstream remote and sync your local copy
4. Branch each set of work
5. Push the work to your own repository
6. Create a new pull request
7. Look out for any code feedback and respond accordingly

This book was built from ground-up in a "collaborative fashion", using a small set of Open Source tools and technologies.

Collaboration relies on Git - a free and open source distributed version control system and other tools around Git:

• Gogs - Go Git Service, a painless self-hosted Git Service, which provides a Github like user interface and workflow.
• Git flow - a collection of Git extensions to provide high-level repository operations for Vincent Driessen's branching model;
• Git Flow Hooks - some useful hooks for git-flow (AVH Edition) by Jaspern Brouwer.

The book sources are written on Markdown format, taking advantage of gitbook-cli.

Environment setup

If you want to contribute to this book, you should setup the following tools on your system:

1. To install Git, please follow the official instructions according to your system's configuration;
2. Now that you have Git, you should install Git Flow and Git Flow Hooks;
3. Last but not least, setup GitBook CLI.

How to start

Ok, now you're ready to contribute.

Fork the go-webapp-scp repo and then clone your own repository.

The next step is to enable Git Flow hooks; enter your local repository

$ cd go-webapp-scp

and run

$ git flow init

We're good to go with git flow default values.

In a nutshell, everytime you want to work on a section, you should start a "feature":

$ git flow feature start my-new-section

To keep your work safe, don't forget to publish your feature:

$ git flow feature publish

Once you're ready to merge your work with others, you should go to the main repository and open a Pull Request to the develop branch. Then, someone will review your work, leave any comments, request changes and/or simply merge it on branch develop of project's main repository.

As soon as this happens, you'll need to pull the develop branch to keep your own develop branch updated with the upstream. The same way as on a release, you should update your master branch.

When you find a typo or something that needs to be fixed, you should start a "hotfix"

$ git flow hotfix start

This will apply your change on both develop and master branches.

As you can see, until now there were no commits to the master branch. Great! This is reserved for releases. When the work is ready to become publicly available, the project owner will do the release.

While in the development stage, you can live-preview your work. To get Git Book tracking file changes and to live-preview your work, you just need to run the following command on a shell session

$ npm run serve

The shell output will include a localhost URL where you can preview the book.

How to Build

If you have node installed, you can run:

$ npm i && node_modules/.bin/gitbook install && npm run build

You can also build the book using an ephemeral Docker container:

$ docker-compose run -u node:node --rm build