axone-protocol / axone-contract-schema Goto Github PK

Proposal to adopt Magefile for build management

Discussion Participants: @bdeneux, @amimart, @ccamel

Current situation

Our current build processes are entirely handled through GitHub Actions, which manages various tasks directly within the GitHub CI pipeline. While functional, this setup lacks a dedicated build management system, making it challenging to maintain and scale efficiently as our project grows and attracts more contributors.

Overview

This proposal recommends the adoption of Magefile as our primary build management tool. By leveraging the Go programming language, Magefile introduces a modernized approach to managing and automating builds.

Implementing Magefile will streamline our build processes, enhance portability across different environments, and improve the overall development experience for both current developers and new contributors.

Rationale

• Improved readability and maintainability: Magefiles, written in Go, offer superior readability and maintainability compared to traditional Makefile syntax. This change will simplify our build scripts, making them more accessible and easier to manage, particularly for those familiar with Go.
• Platform independence: Unlike the current reliance on Unix-specific features in some of our scripts, Magefile is inherently cross-platform. Adopting Magefile will eliminate platform-specific issues and standardize our build process across all environments.
• Enhanced dependency management: With Magefile, dependencies are explicitly defined within build tasks, which improves the clarity and management of task dependencies and execution order.
• Robust community support: Despite the extensive community surrounding traditional Makefiles, the growing community and ecosystem of Magefile provide continuous improvements and robust support, enhancing our development practices.
• Integration with existing tools: Magefile can seamlessly integrate with GitHub Actions, allowing us to enhance our current CI/CD pipelines rather than replacing them. This integration will enable more sophisticated build scenarios while maintaining the ease of use and flexibility that GitHub Actions provides.

Building on the progress made in issues #25 and #27, we need to enhance our build system to include the ability to publish generated types. This will be achieved through the integration of the Mage build tool.

The proposed enhancements will require updates to our GitHub Actions workflow to accommodate the new publishing steps. The key objectives of this issue are:

1. Publish Go Types: We need to implement functionality to publish Go types and manage package version updates. This will involve creating a new Mage target that handles the generation and publishing of Go types, as well as managing the versioning of the Go package.

2. Publish TypeScript Types on npm: Similarly, we need to create a Mage target for publishing TypeScript types on npm. This target should handle the generation of TypeScript types and their subsequent publishing on npm.

Here is an enum declaration we can find in the schema.d.ts file from @okp4/cogniatrium-schema:

export declare enum RDFXML {
    NQuads = "n_quads",
    NTriples = "n_triples",
    RDFXML = "rdf_xml",
    Turtle = "turtle"
}

When I import RDFXML within a frontend (import { RDFXML } from "@okp4/cognitarium-schema";), I got the following message:

SyntaxError: The requested module '/node_modules/.vite/deps/@okp4_cognitarium-schema.js?t=1695034170441&v=b1b30273' does not provide an export named 'RDFXML'

I am trying to figure out how I can use it. All the other imports work perfectly.

Note that according to the contracts repo, msg.rs from okp4-cognitarium declare DataFormat instead of RDFXML. Strange renaming, don't know if it's related.

Quicktype Issue submitted by @bdeneux: glideapps/quicktype#2410

FYI @amimart @ccamel

Proposal

Currently, we are using our own coded type for managing versions in the magefiles, which is fine.

However, to simplify the code slightly and ensure that versions are managed with complete safety, I suggest we switch to using the hashicorp/go-version library for managing versions. This library provides robust support for SemVer 2.0.0, including handling v prefixed versions seamlessly.

This is a low-priority suggestion, and its relevance and interest can be discussed further.

Issue

Using versions with a v-prefix in the package.json file does not comply with Semantic Versioning v2.0.0, as specified in the SemVer documentation.

For example:

{
    "name": "@axone/cognitarium-schema",
    "version": "v3.0.0",
...
}

The version is listed as v3.0.0 when it should be 3.0.0.

Additionally, it is a good practice, widely adopted, to avoid prefixing npm package versions with v. While npm supports this format for compatibility with older packages (SemVer 1.0), adhering to the standard format ensures better interoperability, imho.

See: npm documentation on Semantic Versioning.

As part of our ongoing efforts to improve and expand our build process, I propose the addition of a Golang target for schema generation. This will allow generate Golang types from our contract schemas, further enhancing the versatility and utility of our build process.

The introduction of this feature is crucial for the future Axone Go SDK. Having the contract types available in Go will facilitate communication with the contract and ensure proper lifecycle process versioning and more.