Skip to content

Commit

Permalink
chore: prepare for v2.2 release
Browse files Browse the repository at this point in the history
  • Loading branch information
retr0h committed Mar 6, 2024
1 parent ccc08e9 commit 185799b
Show file tree
Hide file tree
Showing 8 changed files with 360 additions and 0 deletions.
78 changes: 78 additions & 0 deletions docs/versioned_docs/version-2.2/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
sidebar_position: 3
---

# Configuration

Gilt uses [Viper][] to load configuation through multpile methods.

## Config File

Create the giltfile (`Giltfile.yaml`).

Clone the specified `url`@`version` to the configurable path `--gilt-dir`.
Extract the repo the `dstDir` when `dstDir` is provided. Otherwise, copy files
and/or directories to the desired destinations.

```yaml
---
giltDir: ~/.gilt/clone
debug: false
parallel: true
repositories:
- git: https://github.com/retr0h/ansible-etcd.git
version: 77a95b7
dstDir: roles/retr0h.ansible-etcd
- git: https://github.com/retr0h/ansible-etcd.git
version: 1.1
dstDir: roles/retr0h.ansible-etcd-tag
- git: https://github.com/lorin/openstack-ansible-modules.git
version: 2677cc3
sources:
- src: '*_manage'
dstDir: library
- src: nova_quota
dstDir: library
- src: neutron_router
dstFile: library/neutron_router.py
- src: tests
dstDir: tests
commands:
- cmd: ansible-playbook
args:
- -i,
- playbook.yml
- cmd: bash
args:
- -c
- who | grep tty
```
## Env Vars
The config file can be overriden/defined through env vars.
```bash
GILT_GILTFILE=Giltfile.yaml \
GILT_GILTDIR=~/.gilt/clone \
GILT_DEBUG=false \
GILT_PARALLEL=0 \
gilt overlay
```

## Command Flags

The config file and/or env vars can be overriden/defined through cli flags.

```bash
gilt \
--gilt-file=Giltfile.yaml \
--gilt-dir=~/.gilt/clone \
--debug \
--parallel=false \
overlay
```

<!-- prettier-ignore-start -->
[Viper]: https://github.com/spf13/viper
<!-- prettier-ignore-end -->
120 changes: 120 additions & 0 deletions docs/versioned_docs/version-2.2/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
sidebar_position: 6
---

# Contributing

Contributions to Gilt are very welcome, but we ask that you read this document
before submitting a PR.

:::note

This document applies to the [Gilt][] repository.

:::

## Before you start

- **Check existing work** - Is there an existing PR? Are there issues discussing
the feature/change you want to make? Please make sure you consider/address
these discussions in your work.
- **Backwards compatibility** - Will your change break existing Giltfiles? It is
much more likely that your change will merged if it backwards compatible. Is
there an approach you can take that maintains this compatibility? If not,
consider opening an issue first so that API changes can be discussed before
you invest your time into a PR.

## 1. Setup

- **Go** - Gilt is written in [Go][]. We always support the latest two major Go
versions, so make sure your version is recent enough.
- **Node.js** - [Node.js][] is used to host Gilt's documentation server and is
required if you want to run this server locally.

## 2. Making changes

- **Code style** - Try to maintain the existing code style where possible. Go
code should be formatted by [`gofumpt`][gofumpt] and linted using
[`golangci-lint`][golangci-lint]. Any Markdown or TypeScript files should be
formatted and linted by [Prettier][]. This style is enforced by our CI to
ensure that we have a consistent style across the project. You can use the
`task fmt:check` command to lint the code locally and the `task fmt` command
to automatically fix any issues that are found.
- **Documentation** - Ensure that you add/update any relevant documentation. See
the [updating documentation](#updating-documentation) section below.
- **Tests** - Ensure that you add/update any relevant tests and that all tests
are passing before submitting the PR. See the [writing tests](#writing-tests)
section below.

### Running your changes

To run Gilt with working changes, you can use `go run main.go overlay`.

### Updating documentation

Gilt uses [Docusaurus][] to host a documentation server. The code for this is
located in the Gilt repository. This can be setup and run locally by using
`task docs:start` (requires `nodejs` & `yarn`). All content is written in
Markdown and is located in the `docs/docs` directory. All Markdown documents
should have an 80 character line wrap limit (enforced by Prettier).

### Writing tests

When making a changes, consider whether new tests are required. These tests
should ensure that the functionality you are adding will continue to work in the
future. Existing tests may also need updating if you have changed Gilt's
behavior.

You may also consider adding unit tests for any new functions you have added.
The unit tests should follow the Go convention of being location in a file named
`*_test.go` in the same package as the code being tested.

Integration tests are located in the `tests` directory and executed by [Bats][].

## 3. Committing your code

Try to write meaningful commit messages and avoid having too many commits on the
PR. Most PRs should likely have a single commit (although for bigger PRs it may
be reasonable to split it in a few). Git squash and rebase is your friend!

If you're not sure how to format your commit message, check out [Conventional
Commits][]. This style is enforced, and is a good way to make your commit
messages more readable and consistent.

## 4. Submitting a PR

- **Describe your changes** - Ensure that you provide a comprehensive
description of your changes.
- **Issue/PR links** - Link any previous work such as related issues or PRs.
Please describe how your changes differ to/extend this work.
- **Examples** - Add any examples or screenshots that you think are useful to
demonstrate the effect of your changes.
- **Draft PRs** - If your changes are incomplete, but you would like to discuss
them, open the PR as a draft and add a comment to start a discussion. Using
comments rather than the PR description allows the description to be updated
later while preserving any discussions.

## FAQ

> I want to contribute, where do I start?
All kinds of contributions are welcome, whether its a typo fix or a shiny new
feature. You can also contribute by upvoting/commenting on issues or helping to
answer questions.

> I'm stuck, where can I get help?
If you have questions, feel free open a [Discussion][] on GitHub.

<!-- prettier-ignore-start -->
[Gilt]: https://github.com/retr0h/gilt
[Go]: https://go.dev
[Node.js]: https://nodejs.org/en/
[gofumpt]: https://github.com/mvdan/gofumpt
[golangci-lint]: https://golangci-lint.run
[Prettier]: https://prettier.io/
[Docusaurus]: https://docusaurus.io
[Discussion]: https://github.com/retr0h/gilt/discussions
[Conventional Commits]: https://www.conventionalcommits.org
[Bats]: https://github.com/bats-core/bats-core
<!-- prettier-ignore-end -->
23 changes: 23 additions & 0 deletions docs/versioned_docs/version-2.2/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
sidebar_position: 2
---

# Installation

## Homebrew Tap

```bash
brew install retr0h/tap/gilt
```

## Go Install

```bash
go install github.com/retr0h/gilt/v2@latest
```

## Python

```bash
pip3 install python-gilt
```
42 changes: 42 additions & 0 deletions docs/versioned_docs/version-2.2/intro.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
slug: /
sidebar_position: 1
title: Home
---

# Gilt

<img src="img/gilt.png" align="left" width="250px" height="250px" />

Gilt is a tool which aims to make repo management, manageable. Gilt clones
repositories at a particular version, then overlays the repository to the
provided destination. An alternate approach to "vendoring".

What makes Gilt interesting, is the ability to overlay particular files and/or
directories from the specified repository to given destinations. Originally,
this was quite helpful for those using Ansible, since libraries, plugins, and
playbooks are often shared, but Ansible's [Galaxy][] has no mechanism to handle
this. Currently, this is proving useful for overlaying [Helm charts][].

<br clear="left"/>

## Alternatives

- [Repo][]
- [Git submodules][]
- [Git subtree][]

## History

This project is a golang port of [Gilt][py-gilt], and aims to correct poor
decisions made in the python version, primarially around config syntax,
portability, and reproducibility.

<!-- prettier-ignore-start -->
[Galaxy]: https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html
[Helm charts]: https://helm.sh/docs/topics/charts/
[Repo]: https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md
[Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[Git subtree]: https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt
[py-gilt]: http://gilt.readthedocs.io/en/latest/
<!-- prettier-ignore-end -->
29 changes: 29 additions & 0 deletions docs/versioned_docs/version-2.2/testing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
sidebar_position: 5
---

# Testing

Check installed dependencies:

```bash
task deps:check
```

To execute tests:

```bash
task test
```

Auto format code:

```bash
task fmt
```

List helpful targets:

```bash
task
```
59 changes: 59 additions & 0 deletions docs/versioned_docs/version-2.2/usage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
sidebar_position: 4
---

# Usage

## CLI

### Init Configuration

Initializes config file in the shell's current working directory:

```bash
gilt init
```

### Overlay Repository

Overlay a remote repository into the destination provided.

```bash
gilt overlay
```

### Debug

Display the git commands being executed.

```bash
gilt --debug overlay
```

## Package

### Overlay Repository

See example client in `examples/go-client/`.

```go
func main() {
debug := true
logger := getLogger(debug)

c := config.Repositories{
Debug: debug,
GiltDir: "~/.gilt",
Repositories: []config.Repository{
{
Git: "https://github.com/retr0h/ansible-etcd.git",
Version: "77a95b7",
DstDir: "../tmp/retr0h.ansible-etcd",
},
},
}

var r repositoriesManager = repositories.New(c, logger)
r.Overlay()
}
```
8 changes: 8 additions & 0 deletions docs/versioned_sidebars/version-2.2-sidebars.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"docsSidebar": [
{
"type": "autogenerated",
"dirName": "."
}
]
}
1 change: 1 addition & 0 deletions docs/versions.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[
"2.2",
"2.1.2",
"2.1.1",
"2.0.3"
Expand Down

0 comments on commit 185799b

Please sign in to comment.