aureliano / caravela

Caravela is a Go library to support program update automation. Especially those built and released with goreleaser.

caravela

Caravela is a Go library to support program update automation. Especially those built and released with goreleaser.

Some platforms, such as GitHub and GitLab, provide an API for querying and retrieving software versions. Indeed, this library queries those API to check for new versions and even updates the program.

Currently, caravela requires Go version 1.17 or greater. Caravela tracks Go's version support policy. We do our best not to break older versions of Go if we don't have to, but due to tooling constraints, we don't always test older versions.

Installation

To install Caravela, use go get:

go get github.com/aureliano/caravela

Or you can install specific version as:

go get github.com/aureliano/caravela/v0

Or even add it as a project depency of your module:

require github.com/aureliano/caravela v0

Staying up to date

To update Caravela to the latest version, use go get -u github.com/aureliano/caravela.

Usage

The most common application of this library would be to chain checking for updates with updating.

The example below shows how you do this by notifying the user if an update is available. Then the user is asked if he wants to update the program. And the program is updated as confirmed by the user.

// ...

prov := provider.GithubProvider{
	Host:        "api.github.com",
	Ssl:         true,
	ProjectPath: "aureliano/caravela",
}

release, err := caravela.CheckUpdates(caravela.Conf{
	Version: "0.1.0",
	Provider: prov,
})

if err != nil {
	fmt.Printf("Check updates has failed! %s\n", err)
} else {
	fmt.Printf("[WARN] There is a new version available. Would you like to update this program?")

	// ...
	// Ask user whether to update or not.
	// ...

	if shouldUpdate {
		err = caravela.Update(caravela.Conf{
			Version:     "0.1.0",
			Provider: prov,
		})

		if err != nil {
			fmt.Println(err)
			os.Exit(1)
		} else {
			fmt.Printf("New version %s was successfuly installed!\n", release.Name)
		}
	}
}

// ...

Examples

Some examples are in the example module. There are some usage samples such as check updates and update.

Integration tests

You can run integration tests from the test directory. The command make integration-test will execute some programs, that use the exported functions, and check updates and update.

Contributing

Please feel free to submit issues, fork the repository and send pull requests!

Reporting issues

Bugs, feature requests, and development-related questions should be directed to our GitHub issue tracker. If reporting a bug, please try and provide as much context as possible such as your operating system, Go version, and anything else that might be relevant to the bug. For feature requests, please explain what you're trying to do, and how the requested feature would help you do that.

Security related bugs can either be reported in the issue tracker.

Submitting a patch

1. It's generally best to start by opening a new issue describing the bug or feature you're intending to fix. Even if you think it's relatively minor, it's helpful to know what people are working on. Mention in the initial issue that you are planning to work on that bug or feature so that it can be assigned to you.

2. Follow the normal process of forking the project, and setup a new branch to work in. It's important that each group of changes be done in separate branches in order to ensure that a pull request only includes the commits related to that bug or feature.

3. Go makes it very simple to ensure properly formatted code, so always run go fmt on your code before committing it. You should also run go vet or make code-lint over your code. This will help you find common style issues within your code and will keep styling consistent within the project.

4. Any significant changes should almost always be accompanied by tests. The project already has good test coverage, so look at some of the existing tests if you're unsure how to go about it. gocov and gocov-html are invaluable tools for seeing which parts of your code aren't being exercised by your tests.

5. Please run:

• make test
• make code-lint
• make integration-test

The make test command will run tests inside your code. This will help you spot places where code might be faulty before committing.

The make integration-test command will run integration tests to verify that the exported code that is called by clients works.

And the make code-lint command will check linting and styling over your code, keeping the project consistent formatting-wise.

Do your best to have well-formed commit messages for each change. This provides consistency throughout the project, and ensures that commit messages are able to be formatted properly by various git tools.

Finally, push the commits to your fork and submit a pull request.

NOTE: Please do not use force-push on PRs in this repo, as it makes it more difficult for reviewers to see what has changed since the last code review.

Other notes on code organization

Currently, all exposed features - check updates and update - are defined in the main file at the base directory. Such features are delegated to providers according to where releases were published. That said, a Github provider must be a provider/github.go file as is provider/gitlab.go to Gitlab. So use that as your guide for where to put new providers.

Maintainer's Guide

Always try to maintain a clean, linear git history. With very few exceptions, running git log should not show a bunch of branching and merging.

Never use the GitHub "merge" button, since it always creates a merge commit. Instead, check out the pull request locally (these git aliases help), then cherry-pick or rebase them onto master. If there are small cleanup commits, especially as a result of addressing code review comments, these should almost always be squashed down to a single commit. Don't bother squashing commits that really deserve to be separate though. If needed, feel free to amend additional small changes to the code or commit message that aren't worth going through code review for.

If you made any changes like squashing commits, rebasing onto master, etc, then GitHub won't recognize that this is the same commit in order to mark the pull request as "merged". So instead, amend the commit message to include a line "Fixes #0", referencing the pull request number. This would be in addition to any other "Fixes" lines for closing related issues. If you forget to do this, you can also leave a comment on the pull request. If you made any other changes, it's worth noting that as well.

Versioning

This project follows the Semantic Versioning - semver - for tagging releases of the package.

• The major version is incremented with any incompatible change.
• The minor version is incremented with any backwards compatible change.
• The patch version is incremented with any backwards compatible bug-fixes.

License

This project is licensed under the terms of the MIT license found in the LICENSE file.

caravela's Issues

Integration tests

Implement integration - check updates and update - on both providers GitHub and GitLab.

Improve base documentation

Improve base documentation on README.md.

Update

Update program.

Inputs:

• Provider
• Process name
• Current version

Actions:

• Check for updates
• Return error if current version is up to date
• Download assets
• Decompress binary file
• Verify checksum
• Install files
• Remove installation assets

Output:

• Error

Installer

Install decompressed files #5 replacing the ones based on current process execution. See os.Executable.

Check updates returns a nil release when there is no one

Check updates returns a new release when there is no one. It causes a panic as describe bellow.

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x721cca]

goroutine 1 [running]:
github.com/aureliano/caravela/updater.findUpdateUseCache({0xa68900, 0xc000109b30}, {0xa6cf30, 0xc00003a880})
	/go/pkg/mod/github.com/aureliano/[email protected]/updater/find_update.go:46 +0x8a
github.com/aureliano/caravela/updater.FindUpdate({0xa68900?, 0xc000109b30?}, {0xa6cf30?, 0xc00003a880?}, {0xa667b8, 0xa}, 0x0?)
	/go/pkg/mod/github.com/aureliano/[email protected]/updater/find_update.go:23 +0x51
github.com/aureliano/caravela.CheckUpdates({{0xa667b8, 0xa}, {0xa6cf30, 0xc00003a880}, 0x10e2100, 0x0})
	/go/pkg/mod/github.com/aureliano/[email protected]/caravela.go:37 +0x136

Ignore cache

Add a property to Conf struct in order to ignore reading last release from cache.

• Add property IgnoreCache to Conf struct.
• Add property IgnoreCache = true on examples.

Go releaser

Add support for releasing with goreleaser.

GitHub provider

Implementation of a GitHub provider. Besides, write some examples of how to check updates and update using the GitHub provider.

• Implment the GitHub provider.
• Write example programs.
• Update usage section on provider/doc.go

Continuous integration

Create a pipeline with those jobs:

• install-dependencies (cache them to avoid downloading again)
• check-code-format
• check-code-lint
• unit-test
• build-project
• release-deploy

Downloader

Given a release, download files (compressed binary and checksums) based on metadata to an installation directory.

Decompressor

Decompress a binary file downloaded as described at #4. Given a file path, resolve the file type and decompress supported formats: zip and tar.gz/tgz.

Badges

Add badges for:

• Build: https://github.com/aureliano/caravela/actions/workflows/go.yml/badge.svg
• Reference: https://pkg.go.dev/badge/github.com/
• Coverage: converalls?
• Go report card
• Quality gate status

Go doc

Write code documentation to be generated and exposed at pkg.go.dev. Reference: https://go.dev/blog/godoc

Interface provider

Create an interface that will be a provider used by methods that will update and check for updates. Afterwards, each API will implement its own provider.

• Fetch last release: query API for the last version released.
• Cache release: store access to API locally.
• Restore cache release: restore cached release query.

Serialization

Serialize and deserialize release metadata to be used on cache release.

Comparator

Implement a comparator function following this specification.

Artifact checksum

Apply checkum validation on downloaded file #4.

Internationalization

Implement some kind of internationalization to error messages. Maybe go-i18n and jibber_jabber?

Gitlab provider

Implementation of a Gitlab provider described at #1.

Check for updates

Check for updates.

Inputs:

• Provider
• Current version

Actions:

• Restore cache release
• Not having cached release, fetch da last release and cache the result
• Compare last release with current version
• If last release is greater then current one, return last release; nil otherwise

Outputs:

• The last release
• Error

Call internationalization

Add internationalization configuration as parameter of both: check for updates and update methods.