From 1e748a3c540bc421f9112a119ca886f92092491f Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sat, 2 Jul 2016 16:18:53 +0300 Subject: [PATCH] CONTRIBUTING.md added --- .ci/before_script.sh | 8 ++-- .ci/script.sh | 5 +-- .travis.yml | 12 ++++-- CONTRIBUTING.md | 86 ++++++++++++++++++++++++++++++++++++++ LICENSE.md | 21 ++++++++++ README.md | 20 +++++---- man/man7/git-secret.7.ronn | 28 ++++++------- utils/hooks/post-commit.sh | 6 +-- utils/hooks/pre-commit.sh | 4 +- 9 files changed, 149 insertions(+), 41 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE.md diff --git a/.ci/before_script.sh b/.ci/before_script.sh index acdb3aa2..a3712c76 100644 --- a/.ci/before_script.sh +++ b/.ci/before_script.sh @@ -17,9 +17,7 @@ if [[ "$GITSECRET_DIST" == "brew" ]]; then fi # Local linux (standart build): -if [[ "$GITSECRET_DIST" == "none" ]]; then - if [[ "$GITSECRET_GPG_DEP" == "gnupg2" ]]; then - # Installing custom GPG version: - sudo apt-get install -y gnupg2 - fi +if [[ "$GITSECRET_DIST" == "none" ]] && [[ "$GITSECRET_GPG_DEP" == "gnupg2" ]]; then + # Installing custom GPG version: + sudo apt-get install -y gnupg2 fi diff --git a/.ci/script.sh b/.ci/script.sh index 46391f76..3a441376 100644 --- a/.ci/script.sh +++ b/.ci/script.sh @@ -15,7 +15,7 @@ if [[ ! -z "$DOCKER_DIST" ]]; then fi # Local builds: -if [[ -z "$DOCKER_DIST" ]]; then +if [[ "$GITSECRET_DIST" == "brew" ]] || [[ "$GITSECRET_DIST" == "brew" ]]; then # Only running `make test` on standard (non-docker) build, # since it is called inside the docker container anyway. make test @@ -24,8 +24,7 @@ fi if [[ ! -z "$(command -v shellcheck)" ]]; then # This means, that `shellcheck` does exist, so run it: echo 'running lint' - find src -type f -name '*.sh' -print0 | xargs -0 -I {} shellcheck {} - find utils -type f -name '*.sh' -print0 | xargs -0 -I {} shellcheck {} + find src utils -type f -name '*.sh' -print0 | xargs -0 -I {} shellcheck {} # TODO: add tests to lint # see: https://github.com/koalaman/shellcheck/issues/709 fi diff --git a/.travis.yml b/.travis.yml index f4ec83e3..fb99efa4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -25,16 +25,20 @@ matrix: env: GITSECRET_DIST="none"; GITSECRET_GPG_DEP="gnupg"; SECRETS_GPG_COMMAND="gpg" sudo: required language: ruby + - os: linux + env: GITSECRET_DIST="none"; GITSECRET_GPG_DEP="gnupg2"; SECRETS_GPG_COMMAND="gpg2" + sudo: required + language: ruby + - os: linux + env: GITSECRET_DIST="shellcheck" + sudo: required + language: ruby addons: apt: sources: - debian-sid packages: - shellcheck - - os: linux - env: GITSECRET_DIST="none"; GITSECRET_GPG_DEP="gnupg2"; SECRETS_GPG_COMMAND="gpg2" - sudo: required - language: ruby - os: osx env: GITSECRET_DIST="brew"; GITSECRET_GPG_DEP="gnupg"; SECRETS_GPG_COMMAND="gpg" sudo: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..8dd802d6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing + +Your contributions are always welcome! + +## Process + +### Environment + +Before starting make sure you have: + +* git +* bash +* gnupg (or gnupg2) +* [shellcheck](https://github.com/koalaman/shellcheck) + +Only required if dealing with manuals, `gh-pages` or releases: + +* ruby, ruby-dev + +### Getting started + +1. Create your own or pick an opened issue from the [tracker](https://github.com/sobolevn/git-secret/issues). Take a look at the [`help-wanted` tag](https://github.com/sobolevn/git-secret/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) +2. Fork and clone your repository: `git clone https://github.com/${YOUR_NAME}/git-secret.git` +3. Make sure that everything works fine by running `make test` + +### Development Process + +1. Firstly, you will need to setup development hooks with `make install-hooks` +2. Make changes to the files that need to be changed +3. When making changes to any files inside `src/` you will need to rebuild the binary `git-secret` with `make clean && make build` command +4. Run [`shellcheck`](https://github.com/koalaman/shellcheck) against all your changes with `find src utils -type f -name '*.sh' -print0 | xargs -0 -I {} shellcheck {}` +5. Now, add all your files to the commit with `git add --all` and commit changes `git commit`, make sure you write a good commit message, which will explain your works +6. When running `git commit` the tests will run automatically, you commit will be canceled if they fail +7. Push to your repository, make a pull-request against `develop` branch. Please, make sure you have *one* commit per pull-request + +### Branches + +We have three long-live branches: `master`, `staging` and `develop` (and `gh-pages`). + +It basically looks like that: + +> `your-branch` -> `develop` -> `staging` -> `master` + +* `master` branch is protected, since `antigen` and tools like it installs the app from main branch directly. So only fully tested code goes there +* `staging` - this brach is used to create a new `git` tag and a `github` release, then it gets merged into `master` +* `develop` is where the development is done and the branch you should send your pull-requests to + +### Continuous integration + +CI is done with the help of `travis`. `travis` handles multiple environments: + +* `Docker`-based jobs, or so-called 'integration tests', these tests creates a local release, installs it with the package-manager and then runs unit-tests and system checks +* `OSX` jobs, they just assure that everything will work under `OSX` +* Native `travis` jobs, which handles basic unit-tests and style-checks + +### Release process + +The release process is defined in the `git`-hooks and `.travis.yml`. + +When creating a commit inside the `staging` branch (it is usually a documentation and changelog update with the version bump inside `src/version.sh`) it will trigger two main events. + +Firstly, new manuals will be created and added to the current commit with `make build-man` on `pre-commit` hook. + +Secondly, after the commit is successfully created it will also trigger `make build-gh-pages` target on `post-commit` hook, which will push new manuals to the https://sobolevn.github.io/git-secret/. And the new `git` tag will be automatically created if the version is changed: + +```bash +if [[ "$NEWEST_TAG" != "v${SCRIPT_VERSION}" ]]; then + git tag -a "v${SCRIPT_VERSION}" -m "version $SCRIPT_VERSION" +fi +``` + +Then it will be merged inside `master` when ready. + +#### Travis releases + +When creating a commit inside `master` branch `travis` on successful build will publish new `deb` and `rpm` packages to [`bintray`](https://bintray.com/sobolevn). + +If you wish to override previous release (*be careful*) you will need to add `"override": 1 ` into `matrixParams`, see `deb-deploy.sh` and `rpm-deploy.sh` + +#### Manual releases + +Releases to `brew` are made manually. + +#### Dockerhub releases + +[`Dockerhub`](https://hub.docker.com/r/sobolevn/git-secret/) contains `Docker` images with different OS'es used for testing. It is updated via a `github` webhook on commit into `master`. diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..cf38dad3 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2016 Nikita Sobolev + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index a2201a7b..e438eafc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # git-secret -[![Build Status](https://secure.travis-ci.org/sobolevn/git-secret.png?branch=master)](https://travis-ci.org/sobolevn/git-secret) +[![Build Status](https://secure.travis-ci.org/sobolevn/git-secret.png?branch=master)](https://travis-ci.org/sobolevn/git-secret) [![Dockerhub](https://img.shields.io/docker/pulls/sobolevn/git-secret.svg)](https://hub.docker.com/r/sobolevn/git-secret/) + +## What is `git-secret`? + +`git-secret` is a bash tool to store your private data inside a git repo. How’s that? Basically, it just encrypts, using `gpg`, the tracked files with the public keys of all the users that you trust. So everyone of them can decrypt these files using only their personal secret key. Why deal with all this private-public keys stuff? Well, to make it easier for everyone to manage access rights. There are no passwords that change. When someone is out - just delete his public key, re-encrypt the files, and he won’t be able to decrypt secrets anymore. ## Preview @@ -14,16 +18,14 @@ See the [git-secret site](https://sobolevn.github.io/git-secret/). See the [installation section](https://sobolevn.github.io/git-secret/#installation). -## Status - -This project is still under development. See [https://github.com/sobolevn/git-secret/milestones](milestones) for the refence. +## Contributing -## Testing +See [CONTRIBUTING.md](CONTRIBUTING.md). -For testing this project uses [`bats`](https://github.com/sstephenson/bats). You can install it by running `make install-test`. -To run tests call: `make test`. It will download and install `bats` into `vendor/bats` if it's not installed yet. +## Changelog +See [CHANGELOG.md](CHANGELOG.md). -## Changelog +## License -See [CHANGELOG.md](CHANGELOG.md) +MIT. See [LICENSE.md](LICENSE.md) for details. diff --git a/man/man7/git-secret.7.ronn b/man/man7/git-secret.7.ronn index 1f685c4f..1785c827 100644 --- a/man/man7/git-secret.7.ronn +++ b/man/man7/git-secret.7.ronn @@ -25,7 +25,7 @@ There's a known problem in server configuration and deploying, when you have to ### Dependencies -`git secret` relies on two dependecies: [`git`][1] and [`gpg`][2]. Download and install them before using this project. `git-secret` is tested to work with: +`git secret` relies on two dependencies: [`git`][1] and [`gpg`][2]. Download and install them before using this project. `git-secret` is tested to work with: git version 2.7.0 gpg (GnuPG) 1.4.20 @@ -47,33 +47,33 @@ There are several ways to install `git-secret`: * `--HEAD` to install `HEAD` version 2. Note, that we have migrated from `tap` to the official `brew` repo +**deb package** + +1. Run `echo "deb https://dl.bintray.com/sobolevn/deb git-secret stable" | sudo tee -a /etc/apt/sources.list` +2. Run `sudo apt-get install git-secret` + +**rpm package** + +1. Run `wget https://bintray.com/sobolevn/rpm/rpm -O bintray-sobolevn-rpm.repo && sudo mv bintray-sobolevn-rpm.repo /etc/yum.repos.d/` +2. Run `sudo yum install git-secret` + **Manual** 1. Clone the repository first: `git clone https://github.com/sobolevn/git-secret.git git-secret` -2. Run `PREFIX="/usr/local" make install`, note that you can install to any prefix in your `PATH` +2. Run `make build` +3. Run `PREFIX="/usr/local" make install`, note that you can install to any prefix in your `PATH` **`antigen` plugin (or any other `oh-my-zsh`-styled plugin-systems)** 1. Add line `antigen bundle sobolevn/git-secret` to your `.zshrc` 2. Run `source ~/.zshrc` or reopen the terminal -**The hard way** - -1. Clone the repository first: `git clone https://github.com/sobolevn/git-secret.git git-secret` -2. Run `cd git-secret && make build` -3. Move `git-secret` file and `man/` folder somewhere inside your `$PATH`, or extend your `$PATH` to contain `git-secret` file and `man/` folder - -**Local `.deb` package** - -1. Download the latest realease [here](https://github.com/sobolevn/git-secret/releases) -2. Unpack, and run `make build-deb`, it is possible to set the output folder with `$SCRIPT_BUILD_DIR` variable. -3. Install the local `.deb` package with `dpkp -i git-secret-package-name.deb`, note that this command may require `sudo` and the package name will be different ## Usage These steps cover the basic process of using `git-secret`: 0. Before starting, make sure you have created `gpg` RSA key-pair: public and secret key identified by your email address. -1. Initialize `git-secret` repository by running `git secret init` command. `.gitsecret/` folder will be created. +1. Initialize `git-secret` repository by running `git secret init` command. `.gitsecret/` folder will be created, *note* that `.gitsecret/` folder [should not be ignored](https://github.com/sobolevn/git-secret/issues/39). 2. Add first user to the system by running `git secret tell your@gpg.email-id`. 3. Now it's time to add files you wish to encrypt inside the `git-secret` repository. It can be done by running `git secret add ` command. Make sure these files are ignored, otherwise `git secret` won't allow you to add them, as these files will be stored unencrypted. 4. When done, run `git secret hide` all files, which you have added by `git secret add` command will be encrypted with added public-keys by the `git secret tell` command. Now it is safe to commit your changes. **But**. It's recommended to add `git secret hide` command to your `pre-commit` hook, so you won't miss any changes. diff --git a/utils/hooks/post-commit.sh b/utils/hooks/post-commit.sh index 7b20fe67..dff89cee 100755 --- a/utils/hooks/post-commit.sh +++ b/utils/hooks/post-commit.sh @@ -4,12 +4,10 @@ set -e BRANCH_NAME=$(git branch | grep '\*' | sed 's/* //') -if [[ "$BRANCH_NAME" == 'master' ]]; then +if [[ "$BRANCH_NAME" == 'staging' ]]; then # Build new web documentation: make build-gh-pages -fi - -if [[ "$BRANCH_NAME" == 'staging' ]]; then + # Compare script version and the latest tag: NEWEST_TAG=$(git describe --abbrev=0 --tags) SCRIPT_VERSION=$(bash "${PWD}/git-secret" --version) diff --git a/utils/hooks/pre-commit.sh b/utils/hooks/pre-commit.sh index c00642c6..f14a52c7 100755 --- a/utils/hooks/pre-commit.sh +++ b/utils/hooks/pre-commit.sh @@ -4,13 +4,13 @@ set -e BRANCH_NAME=$(git branch | grep '\*' | sed 's/* //') -if [[ $BRANCH_NAME != '(no branch)' ]]; then +if [[ "$BRANCH_NAME" != '(no branch)' ]]; then unset GIT_WORK_TREE # Run tests: make test - if [[ $BRANCH_NAME == "master" ]]; then + if [[ "$BRANCH_NAME" == "staging" ]]; then # Build new manuals: make build-man