Skip to content

Commit

Permalink
Release v0.3.0.
Browse files Browse the repository at this point in the history
  • Loading branch information
@octavore
octavore committed May 24, 2018
1 parent 7aac179 commit f1c19c1
Showing 1 changed file with 61 additions and 36 deletions.
97 changes: 61 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,43 @@
# Ketchup

[![Go Report Card](https://goreportcard.com/badge/github.com/ketchuphq/ketchup)](https://goreportcard.com/report/github.com/ketchuphq/ketchup)
[![CircleCI](https://circleci.com/gh/ketchuphq/ketchup.svg?style=svg)](https://circleci.com/gh/ketchuphq/ketchup)
[![Coverage Status](https://coveralls.io/repos/github/ketchuphq/ketchup/badge.svg?branch=master)](https://coveralls.io/github/ketchuphq/ketchup?branch=master)
[![CircleCI](https://circleci.com/gh/ketchuphq/ketchup.svg?style=svg)](https://circleci.com/gh/ketchuphq/ketchup)


[Ketchup](https://ketchuphq.com) is a CMS that aims to be...

- Easy to install and run
- Pretty snappy
- Extensible for making custom builds
- Easy to create and use your own templates
- Automatic HTTPS via Let’s Encrypt
[Ketchup](https://ketchuphq.com) is a developer-first CMS.

- **BYO (bring your own) version-controlled templates**. Develop your templates outside of Ketchup, and pull them in with built-in support for git.
- **Customizable editor**. Templates declare content fields for frontend to render, so your editorial team can make edits easily.
- **[First class JSON API](https://ketchuphq.com/docs/api)**. Use Ketchup as a headless CMS by fetching content programmatically to power your own static websites or single-page webapps.
- **Automatic HTTPS**. Let's Encrypt certificate provisioning and renewal built-in.
- **Easy to deploy**. One binary, database included.
- Other features include file uploads, Markdown and WYSIWYG editors, content preview, etc.

### Table of contents

- [Usage](#usage)
- [Development](#development)
- [1. Getting started](#1-getting-started)
- [2. Compiling](#2-compiling)
- [Watching](#watching)
- [3. Development](#3-development)
- [Protobuf API](#protobuf-api)
- [4. Releasing new versions](#4-releasing-new-versions)
- [Extending Ketchup](#extending-ketchup)
- [Architectural decisions](#architectural-decisions)
- [Changelog](#changelog)
- [0.3.0 - Relaxed React](#030---relaxed-react)
- [0.2.0 - Tranquil Themes](#020---tranquil-themes)
- [0.1.0 - Initial Release!](#010---initial-release)
- [License](#license)

## Usage

If you’re interested in _using_ Ketchup, please check out the documentation at [ketchuphq.com/docs](https://ketchuphq.com/docs) (which is itself built with Ketchup — dogfood!).

If you want to download the latest release, visit the [Releases page](https://github.com/ketchuphq/ketchup/releases).

If you'd like to see some screenshots, see [here](https://ketchuphq.com/docs/screenshots).
- If you’re interested in _using_ Ketchup, please check out the documentation at [ketchuphq.com/docs](https://ketchuphq.com/docs) (which is itself built with Ketchup — dogfood!).
- If you want to download the latest release, visit the [Releases page](https://github.com/ketchuphq/ketchup/releases).
- If you want to learn how to develop your own theme, read the [Theme Documentation](https://ketchuphq.com/docs/themes).
- If you'd like to see some screenshots, see [here](https://ketchuphq.com/docs/screenshots).

This readme will focus on how to build and develop Ketchup.

Expand All @@ -32,9 +50,7 @@ These instructions assume you're using OS X, but they should work on Linux as we
To get started, you’ll first need to install the following dependencies, which are used to compile the backend and frontend respectively.

- **Go >=1.9**
- **Node >= 8**
- [NPM](https://www.npmjs.com)
- [Yarn](https://yarnpkg.com/)
- **Node >= 8** with [NPM](https://www.npmjs.com) and [Yarn](https://yarnpkg.com/)

Then, run the following to download frontend and backend dependencies:

Expand All @@ -52,14 +68,29 @@ make

This will first run the frontend compilation (a Gulp task), then embed the frontend assets into `admin/bindata.go`, and finally run `go build`. The result will be a `ketchup` binary in the top-level.


If you want to modify the API, see below for instructions for how to update the proto files and regenerate the corresponding Go structs and Typescript classes.

#### Watching

For ongoing development, it can be a hassle to keep recompiling. There's a `gulp watch` task which you can run in the `admin` folder to recompile Typescript and SASS and output `bindata.go` on changes to frontend code. See [admin/README.md](https://github.com/ketchuphq/ketchup/blob/master/admin/README.md) for more details.

For backend code, there's `./scripts/dev-watch.sh`, which will start a Ketchup server and recompile+restart it on changes to `.go` files.

### 3. Development

For ongoing development, it can be a hassle to keep recompiling. There's a `gulp watch` task which you can run in the `admin` folder to recompile Typescript and SASS and output `bindata.go` on changes to frontend code.
#### Protobuf API

Protobufs are used to describe the API as well as being the serialization for data stored in BoltDB.

To change the API, you’ll need to install the protobuf compiler, `protoc`. If you have Homebrew, running `make prepare-protos` will install it using `brew`, as well as a custom plugin for generating Go output.

You should never edit `*.pb.go` and `./admin/src/js/lib/api.ts` directly. Instead, you should edit the relevant `.proto` protobuf file, and then regenerate those files:

```
make protos
```

For backend code, there's `./scripts/dev-watch.sh`, which will start a Ketchup server and recompile/restart it on changes to `.go` files.
After regenerating, you can recompile the frontend and backend to view your changes.

### 4. Releasing new versions

Expand All @@ -69,7 +100,7 @@ This section is for completeness; you probably won't have to do this.
make release-nr # dry run, only outputs to ./dist
# tag a release, goreleaser uses the latest tag
git tag -a v0.2.0 && git push origin v0.2.0
git tag -a v0.3.0 && git push origin v0.3.0
make release
```

Expand All @@ -78,22 +109,6 @@ Ketchup uses [`goreleaser`](https://github.com/goreleaser/goreleaser) to create
The version of the release is read from the latest git tag.


## Protobuf API

Protobufs are used to describe the API as well as the serialization for data stored in BoltDB.

To change the API, you’ll need to install the protobuf compiler, `protoc`. If you have Homebrew, running `make prepare` will install it using `brew`, as well as a custom plugin for generating Go output.

### Workflow

You should never edit `*.pb.go` and `./admin/src/js/lib/api.ts` directly. Instead, you should edit the relevant `.proto` protobuf file, and then regenerate those files:

```
make protos
```

After regenerating, you can recompile the frontend and backend to view your changes.

## Extending Ketchup

This is a work in progress. The long-term goal is to make it easy to swap out, configure, or add modules, using a custom `main.go` file. The following features are intended to be pluggable:
Expand All @@ -119,6 +134,16 @@ A brief run through of the things without which this project would not exist:

## Changelog

### 0.3.0 - Relaxed React

- Migrated frontend to React.
- Added live preview when editing content.
- Added drag-and-drop file uploads.
- Added `users:list` CLI to list all users from command line.
- Added `/admin/logout` endpoint for logging out.
- Increased server test coverage significantly.
- Fixed [#11](https://github.com/ketchuphq/ketchup/issues/11)

### 0.2.0 - Tranquil Themes

**Major changes**
Expand Down

0 comments on commit f1c19c1

Please sign in to comment.