Skip to content

Latest commit

 

History

History
248 lines (164 loc) · 10.7 KB

README.md

File metadata and controls

248 lines (164 loc) · 10.7 KB
Raw

Community Project header

Tutone

Testing Security Scan Go Report Card GoDoc License CLA assistant Release

Code generation tool

Generate code from GraphQL schema introspection.

Summary

At a high level, the following workflow is used to generate code.

  • tutone fetch calls the NerdGraph API to introspect the schema.
  • The schema is cached in schema.json. This is information about the GraphQL schema
  • tutone generate uses the schema.json + the configuration + the templates to output generated text.

Installation

go install github.com/newrelic/tutone/cmd/tutone@latest

Command Flags

Flags for running the typegen command:

Flag Description
-p <Package Name> Package name used within the generated file. Overrides the configuration file.
-v Enable verbose logging

Getting Started

  1. Create a project configuration file, see configs/tutone.yaml for an example.

  2. Generate a schema.json using the following command:

    $ tutone fetch \
  --config path/to/tutone.yaml \
  --schema path/to/schema.json

  3. Add a ./path/to/package/typegen.yaml configuration with the type you want generated:

    ---
types:
  - name: MyGraphQLTypeName
  - name: AnotherTypeInGraphQL
    createAs: map[string]int

  4. Add a generation command inside the main.go (or equivalent)

    // Package CoolPackage provides cool stuff, based on generated types
//go:generate tutone generate -p $GOPACKAGE
package CoolPackage
// ... implementation ...

  5. Run go generate

  6. Add the ./path/to/package/types.go file to your repo

Configuration

Configuration File

An example configuration can be found in this project repo.

A configuration file is meant to represent a single project, with specifications for which parts of the schema to process.

Please see the config documentation for details about specific fields.

Package Schema

The packages field in the configuration contains the details about which types and mutations to include from the schema, and where the package is located.

Name Required Description
name Yes The name of the package
path Yes Name of the package the output file will be part of (see -p flag)
generators Yes A list of generator names from the generators field
mutations No A list of mutations from which to infer types
types No A list of types from which to start expanding the inferred set of types

Please see the package schema doc for detailed information about the schema structure.

Type Configuration

To fine-tune the types that are created, or not create them at all, the following options are supported:

Name Required Description
name yes Name of the type to match
create_as no Used when creating a new scalar type to determine which Go type to use.
field_type_override no Golang type to override whatever the default detected type would be for a given field.
interface_methods no List of additional methods that are added to an interface definition. The methods are not defined in the code, so must be implemented by the user.
skip_type_create no Allows the user to skip creating a type.

Generators

The generators field is used to describe a given generator. The generator is where the bulk of the work is done. Note that the configuration name referenced must match the name of the attached generated in the pkg/generate/generate.go file.

The generator configuration specifies details about how the generator should adjust the output of the work.

Name Required Description
name Yes The name of the generator used in pkg/generate/generate.go file
fileName No Where to write the output of the generated code within the specified package

Templates

Example templates are available in the templates/ directory, and are dynamically loaded from your project.

Community

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices.

  • Roadmap - As part of the Developer Toolkit, the roadmap for this project follows the same RFC process
  • Issues or Enhancement Requests - Issues and enhancement requests can be submitted in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue.
  • Contributors Guide - Contributions are welcome (and if you submit a Enhancement Request, expect to be invited to contribute it yourself 😁).
  • Community discussion board - Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub.

Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at opensource@newrelic.com.

Development

Requirements

  • Go 1.19.0+
  • GNU Make
  • git

Building

# Default target is 'build'
$ make

# Explicitly run build
$ make build

# Locally test the CI build scripts
# make build-ci

Testing

Before contributing, all linting and tests must pass. Tests can be run directly via:

# Tests and Linting
$ make test

# Only unit tests
$ make test-unit

# Only integration tests
$ make test-integration

Note: You'll need to update testdata/schema.json to the latest GraphQL schema for tests to run correctly.

Commit Messages

Using the following format for commit messages allows for auto-generation of the CHANGELOG:

Format:

<type>(<scope>): <subject>

Type Description Change log?
chore Maintenance type work No
docs Documentation Updates Yes
feat New Features Yes
fix Bug Fixes Yes
refactor Code Refactoring No

Scope

This refers to what part of the code is the focus of the work. For example:

General:

  • build - Work related to the build system (linting, makefiles, CI/CD, etc)
  • release - Work related to cutting a new release

Package Specific:

  • newrelic - Work related to the New Relic package
  • http - Work related to the internal/http package
  • alerts - Work related to the pkg/alerts package

Documentation

Note: This requires the repo to be in your GOPATH (godoc issue)

$ make docs

Releasing

Releases are automated via the Release Github Action on merges to the default branch. No user interaction is required.

Using svu, commit messages are parsed to identify if a new release is needed, and to what extent. Here's the breakdown:

Commit message Tag increase
fix: fixed something Patch
feat: added new button to do X Minor
fix: fixed thing xyz

BREAKING CHANGE: this will break users because of blah		 Major
fix!: fixed something Major
feat!: added blah Major
chore: foo Nothing
refactor: updated bar Nothing

Support

New Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR SUPPORT, although you can report issues and contribute to the project here on GitHub.

Please do not report issues with this software to New Relic Global Technical Support.

Open Source License

This project is distributed under the Apache 2 license.