From fea773f942a46440d0ae4513d0dab294121f2ff6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sat, 20 Jan 2024 15:19:41 -0800 Subject: [PATCH] chore: prepare for v2.0.3 release --- docs/docs/intro.md | 8 +- docs/docusaurus.config.js | 2 +- .../version-2.0.3/configuration.md | 75 +++++++++++ .../version-2.0.3/contributing.md | 120 ++++++++++++++++++ .../version-2.0.3/installation.md | 17 +++ docs/versioned_docs/version-2.0.3/intro.md | 42 ++++++ docs/versioned_docs/version-2.0.3/testing.md | 29 +++++ docs/versioned_docs/version-2.0.3/usage.md | 59 +++++++++ .../version-2.0.3-sidebars.json | 8 ++ docs/versions.json | 1 + 10 files changed, 356 insertions(+), 5 deletions(-) create mode 100644 docs/versioned_docs/version-2.0.3/configuration.md create mode 100644 docs/versioned_docs/version-2.0.3/contributing.md create mode 100644 docs/versioned_docs/version-2.0.3/installation.md create mode 100644 docs/versioned_docs/version-2.0.3/intro.md create mode 100644 docs/versioned_docs/version-2.0.3/testing.md create mode 100644 docs/versioned_docs/version-2.0.3/usage.md create mode 100644 docs/versioned_sidebars/version-2.0.3-sidebars.json diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 97060d1..2110442 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -28,9 +28,9 @@ this. Currently, this is proving useful for overlaying [Helm charts][]. ## History -This project is a golang port of [Gilt][], and aims to correct poor decisions -made in the python version, primarially around config syntax, portability, and -reproducibility. +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. [Galaxy]: https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html @@ -38,5 +38,5 @@ reproducibility. [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 -[Gilt]: http://gilt.readthedocs.io/en/latest/ +[py-gilt]: http://gilt.readthedocs.io/en/latest/ diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 81435f5..3b1aaaa 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -119,7 +119,7 @@ const config = { }, announcementBar: { id: 'announcementBar-3', // Increment on change - content: `🎉️ Gilt has been 💯 rewritten in Go, v2.0.2 is now available! 🥳️`, + content: `🎉️ Gilt has been 💯 rewritten in Go, v2.0.2 is now available! 🥳️`, }, }), }; diff --git a/docs/versioned_docs/version-2.0.3/configuration.md b/docs/versioned_docs/version-2.0.3/configuration.md new file mode 100644 index 0000000..c9ad394 --- /dev/null +++ b/docs/versioned_docs/version-2.0.3/configuration.md @@ -0,0 +1,75 @@ +--- +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 +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 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 \ + overlay +``` + + +[Viper]: https://github.com/spf13/viper + diff --git a/docs/versioned_docs/version-2.0.3/contributing.md b/docs/versioned_docs/version-2.0.3/contributing.md new file mode 100644 index 0000000..c2b6ef2 --- /dev/null +++ b/docs/versioned_docs/version-2.0.3/contributing.md @@ -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. + + +[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 + diff --git a/docs/versioned_docs/version-2.0.3/installation.md b/docs/versioned_docs/version-2.0.3/installation.md new file mode 100644 index 0000000..258c572 --- /dev/null +++ b/docs/versioned_docs/version-2.0.3/installation.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 2 +--- + +# Installation + +## Homebrew Tap + +```bash +brew install retr0h/tap/gilt +``` + +## Go Install + +```bash +go install github.com/retr0h/gilt@latest +``` diff --git a/docs/versioned_docs/version-2.0.3/intro.md b/docs/versioned_docs/version-2.0.3/intro.md new file mode 100644 index 0000000..db724b2 --- /dev/null +++ b/docs/versioned_docs/version-2.0.3/intro.md @@ -0,0 +1,42 @@ +--- +slug: / +sidebar_position: 1 +title: Home +--- + +# Gilt + + + +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][]. + +
+ +## 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. + + +[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/ + diff --git a/docs/versioned_docs/version-2.0.3/testing.md b/docs/versioned_docs/version-2.0.3/testing.md new file mode 100644 index 0000000..2fac839 --- /dev/null +++ b/docs/versioned_docs/version-2.0.3/testing.md @@ -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 +``` diff --git a/docs/versioned_docs/version-2.0.3/usage.md b/docs/versioned_docs/version-2.0.3/usage.md new file mode 100644 index 0000000..f95bb05 --- /dev/null +++ b/docs/versioned_docs/version-2.0.3/usage.md @@ -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() +} +``` diff --git a/docs/versioned_sidebars/version-2.0.3-sidebars.json b/docs/versioned_sidebars/version-2.0.3-sidebars.json new file mode 100644 index 0000000..39332bf --- /dev/null +++ b/docs/versioned_sidebars/version-2.0.3-sidebars.json @@ -0,0 +1,8 @@ +{ + "docsSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index e50f3a7..13e3716 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "2.0.3", "2.0.2", "2.0", "1.0.2"