Skip to content

Commit

Permalink
doc: tidy readme (#4)
Browse files Browse the repository at this point in the history
  • Loading branch information
@plastikfan
plastikfan committed Dec 10, 2024
1 parent 89414c7 commit 2b142d0
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 118 deletions.
2 changes: 2 additions & 0 deletions .vscode/settings.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@
"--fast"
],
"cSpell.words": [
"agenor's",
"astrolib",
"bodyclose",
"bubbletea",
"cmds",
"copyloopvar",
"coverpkg",
Expand Down
129 changes: 11 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 🌟 balloons: ___Go template for library modules___
# 🎈balloons: ___charm bubbletea bubbles___

[![A B](https://img.shields.io/badge/branching-commonflow-informational?style=flat)](https://commonflow.org)
[![A B](https://img.shields.io/badge/merge-rebase-informational?style=flat)](https://git-scm.com/book/en/v2/Git-Branching-Rebasing)
Expand Down Expand Up @@ -26,135 +26,28 @@
<!-- MarkDownLint-disable MD028 -->

<p align="left">
<a href="https://go.dev"><img src="resources/images/go-logo-light-blue.png" width="50" /></a>
<a href="https://go.dev"><img src="resources/images/go-logo-light-blue.png" width="50" alt="go" /></a>
</p>

## 🔰 Introduction

This project is a template to aid in the startup of Go library module projects.
This project will contain functionality that uses entities from the [charm universe](https://charm.sh/) to define tui user interface components utilised by `snivilised` projects. In particular, it contains a `highway` control (custom charm bubble) that aims to provide a front end view of a worker pool, although there is nothing to say that this is it's only application.

### 🎯 Highway

The highway contains multiple lanes representing different threads of execution, underpinned by a worker pool. As activity occurs, the corresponding lane in the highway updates to reflect completion of a job. However it is important to note that the highway, does not need to represent a worker pool, it can represent anything that can be visually represented by the concept of a group of lanes. The motivation for this control came from the need to be able to demonstrate the concurrent behaviour of [🌀 agenor's](https://github.com/snivilised/agenor) navigator and the [🐜 pants](https://github.com/snivilised/pants) worker pool that supports it.

More details to follow...

## 📚 Usage

## 🎀 Features

<p align="left">
<a href="https://onsi.github.io/ginkgo/"><img src="https://onsi.github.io/ginkgo/images/ginkgo.png" width="100" /></a>
<a href="https://onsi.github.io/gomega/"><img src="https://onsi.github.io/gomega/images/gomega.png" width="100" /></a>
<a href="https://onsi.github.io/ginkgo/"><img src="https://onsi.github.io/ginkgo/images/ginkgo.png" width="100" alt="ginkgo" /></a>
<a href="https://onsi.github.io/gomega/"><img src="https://onsi.github.io/gomega/images/gomega.png" width="100" alt="gomega" /></a>
</p>

+ unit testing with [Ginkgo](https://onsi.github.io/ginkgo/)/[Gomega](https://onsi.github.io/gomega/)
+ implemented with [🐍 Cobra](https://cobra.dev/) cli framework, assisted by [🐲 Cobrass](https://github.com/snivilised/cobrass)
+ i18n with [go-i18n](https://github.com/nicksnyder/go-i18n)
+ linting configuration and pre-commit hooks, (see: [linting-golang](https://freshman.tech/linting-golang/)).

## 🔨 Developer Info

By using this template, there is no need to use the cobra-cli to scaffold your application as this has been done already. It should be noted that the structure that is generated by the cobra-cli has been significantly changed in this template, mainly to remove use of the __init()__ function and to minimise use of package level global variables. For a rationale, see [go-without-package-scoped-variables](https://dave.cheney.net/2017/06/11/go-without-package-scoped-variables).

### 📝 Checklist of required changes

The following is list of actions that must be performed before using this template. Most of the changes concern changing the name `balloons` to the name of the new application. As the template is instantiated from github, the new name will automatically replace the top level directory name, that being ___astrolib___.

➕ The following descriptions use owner name ___pandora___ and repo name ___maestro___ as an example. That is to say the client has instantiated ___astrolib___ template into github at url _github.com/pandora/maestro_

#### 🤖 Automated changes

Automated via `automate-checklist.sh` script. When the user instantiates the repo, a github actions workflow is executed which applies changes to the clients repo automatically. The following description describes the changes that are applied on the user's behalf and the workflow is automatically deleted. However, there are other changes that should be made. These compose the manual checklist and should be heeded by the user.

##### ✅ Rename import statements

+ `rename import paths`: global search and replace ___snivilised/balloons___ to ___pandora/maestro___

##### ✅ Identifiers

+ `change astrolibTemplData`: perform a refactor rename (_Rename Symbol_) to ___maestroTemplData___

##### ✅ Global search replace balloons to maestro

Will take care of the following required changes:

+ `change module name`: update the module name inside the .mod file in the root directory
+ `change ApplicationName`: modify to reflect the new application name. This application name is incorporated into the name of any translation files to be loaded.
+ `update BINARY_NAME`: Inside _Taskfile.yml_, change the value of ___BINARY_NAME___ to the name of the client application.
+ `update github action workflows`: change the name of the workflows in the .yaml files to replace ___astrolib___ to ___Maestro___ (note the change of case, if this is important).

##### ✅ Localisation/Internationalisation

+ `change the names of the translation files`: eg change ___astrolib.active.en-GB.json___ to ___maestro.active.en-GB.json___

##### ✅ Miscellaneous automated changes

+ `reset version files`: this is optional because the release process automatically updates the version number according to the tag specified by the user, but will initially contain the version number which reflects the current value of balloons at the time the client project is instantiated.
+ `change SOURCE_ID`: to "github.com/pandora/maestro"

#### 🖐 Manual changes

The following documents manual changes required. Manual checklist:

##### ☑️ Structural changes

+ `github actions workflow`: If the client does not to use github actions workflow automation, then these files ([ci-workflow](.github/workflows/ci-workflow.yml), [release-workflow](.github/workflows/release-workflow.yml), [.goreleaser.yaml](./.goreleaser.yaml)), should be deleted.

+ `rename the widget command`: rename __widget-cmd.go__ and its associated test __widget_test.go__ to whatever is the first command to be implemented in the application. The widget command can serve as a template as to how to define a new command, without having to start from scratch. It will be easier for the user to modify an existing command, so just perform a case sensitive search and replace for ___widget/Widget___ and replace with ___Foo/foo___ where foo represents the new command to be created.

+ `review bootstrap.go`: this will need to be modified to invoke creation of any custom commands. The `execute` method of __bootstrap__ should be modified to invoke command builder. Refer to the `widget` command to see how this is done.

#### ☑️ Github changes

Unfortunately, github doesn't copy over the template project's settings to the client project, so these changes must be made manually:

Under `Protect matching branches`

+ `Require a pull request before merging` ✅ _ENABLE_
+ `Require linear history` ✅ _ENABLE_
+ `Do not allow bypassing the above settings` ✅ _ENABLE_

Of course, its up to the user what settings they use in their repo, these are just recommended as a matter of good practice.

#### ☑️ Code coverage

+ `coveralls.io`: add maestro project

#### ☑️ Miscellaneous changes

+ `replace README content`
+ `update email address in copyright statement`: The __root.go__ file contains a placeholder for an email address, update this comment accordingly.
+ `create .env file`: Add any appropriate secrets to a newly created .env in the root directory and to enable the __deploy__ task to work, define a __DEPLOY_TO__ entry that defines where builds should be deployed to for testing
+ `install pre-commit hooks`: just run ___pre-commit install___
+ `update translation file`: Inside _Taskfile.yml_, add support for loading any translations that the app will support. By default, it deploys a translation file for __en-US__ so this needs to be updated as appropriate.

### 🌐 l10n Translations

This template has been setup to support localisation. The default language is `en-GB` with support for `en-US`. There is a translation file for `en-US` defined as __src/i18n/deploy/balloons.active.en-US.json__. This is the initial translation for `en-US` that should be deployed with the app.

Make sure that the go-i18n package has been installed so that it can be invoked as cli, see [go-i18n](https://github.com/nicksnyder/go-i18n) for installation instructions.

To maintain localisation of the application, the user must take care to implement all steps to ensure translate-ability of all user facing messages. Whenever there is a need to add/change user facing messages including error messages, to maintain this state, the user must:

+ define template struct (__xxxTemplData__) in __src/i18n/messages.go__ and corresponding __Message()__ method. All messages are defined here in the same location, simplifying the message extraction process as all extractable strings occur at the same place. Please see [go-i18n](https://github.com/nicksnyder/go-i18n) for all translation/pluralisation options and other regional sensitive content.

For more detailed workflow instructions relating to i18n, please see [i18n README](./resources/doc/i18n-README.md)

### 🧪 Quick Test

To check the app is working (as opposed to running the unit tests), build and deploy:

> task tbd
(which performs a test, build then deploy)

NB: the `deploy` task has been set up for windows by default, but can be changed at will.

Check that the executable and the US language file __maestro.active.en-US.json__ have both been deployed. Then invoke the widget command with something like

> maestro widget -p "P?\<date\>" -t 30
Optionally, the user can also specify the ___directory___ flag:

> maestro widget -p "P?\<date\>" -t 30 -d foo-bar.txt
... where ___foo-bar.txt___ should be replaced with a file that actually exists.

This assumes that the the project name is `maestro`, change as appropriate.

Since the `widget` command uses `Cobrass` option validation to check that the file specified exists, the app will fail if the file does not exist. This serves as an example of how to implement option validation with `Cobrass`.

0 comments on commit 2b142d0

Please sign in to comment.