General

• 1: Migrating to v2
• 2: Contribution Guidelines
• 3: Struct Field Comments

1 - Migrating to v2

Breaking Changes

Goki-wide

• Import paths have been changed from github.com/goki/* to goki.dev/* (for example, github.com/goki/gi changed to goki.dev/gi). All repositories with a changed import URL that were on version 1 are now on version 2 and have a major version URL suffix (for example, goki.dev/gi/v2)
• KiT_* global variables have been renamed to Type* (for example, KiT_Button changed to TypeButton); fixing this should be a simple find and replace for KiT_ => Type
• AddNew* functions and methods have been renamed to New* (for example, AddNewButton changed to NewButton); fixing this should be a simple find a replace for AddNew => New

goki/ki

• Package ki has been moved into the root directory of ki, so it is now imported as just goki.dev/ki/v2
• Support for automatic Ki field children has been removed, so you now have to manage that yourself (see https://github.com/goki/ki/issues/17)

goki/gi/gi

• Defaults() method removed on several widgets (slider, spinbox, scrollbar, etc); it is no longer needed and all calls of it can be deleted.
• MenuButton widget removed; use Button instead, as you can put a menu on any button. If you want the arrow indicator again, put button.Indicator = icons.KeyboardArrowDown
• Action and ButtonBase removed; use Button instead.
• Inactive renamed to Disabled and Active to Enabled. Many node flag functions (eg, SetInactive, IsActive, etc) as well as the actual enum constants must be renamed.
• ClearAct field on TextField converted to LeadingIcon and TrailingIcon; use AddClearAction() to easily replicate the same functionality.
• gi.IconName removed and replaced with icons.Icon; many functions and fields have changed types that must be updated; also, previous icon names may be broken or have changed to new icons, and it is strongly recommended that you use the new icon constants instead of untyped string literals.
• Prop-based styling and configuration removed; set the Style field using AddStyleFunc for styling and directly set the configuration struct fields in your code for configuration.
• Prefs colors removed; use gi.ColorScheme instead.

goki/gi/gist

• Color transformation functions like Highlight now take non-pointer receivers to support function chaining.

goki/gi/units

• units.New* functions have been renamed to units.* (for example, units.NewPx changed to units.Px); fixing this should be a simple find and replace for units.New (although if you use units.NewValue, which is unchanged, you will have to avoid changing that).
• Renamed (units.Context).ToDotsFactor to (units.Context).Dots
• Removed units.Pct and related things (replaced with units.Ew, units.Eh, units.Pw, units.Ph, and related things)
• Renamed units.Context fields ElW, ElH, VpW, and VpH to Ew, Eh, Vw, and Vh respectively.
• Setter functions for units.Context now also take parent size.
• units.Value contains a DotsFunc function (you should use keyed struct literals).

2 - Contribution Guidelines

Bugs

If you have found a bug with a Goki project, create an issue on the GitHub repository for it, tag it with the label “bug,” and state your operating system and the code you were running in the issue. Also, please provide all relevant information about the bug, like any panic stack traces. We will reply to your issue as soon as possible and do our best to fix it quickly, and you should reply to any questions we ask you.

Feature Requests

If you want a new feature to be added to a Goki project, create an issue on the GitHub repository for it, tag it with the label “enhancement,” and clearly describe the feature, why you want it, and how it can be implemented in the issue. We will reply to your issue as soon as possible and either give a timeline on when we plan to implement it or explain why we will not implement it.

Code Contributions

If you want to fix a bug or add a feature on a Goki project, you should create a pull request on the GitHub repository for it, commit your changes on that pull request, and then request for the pull request to be reviewed. We will review it as quickly as possible, give feedback, and merge it if the changes are good.

Documentation Contributions

To improve the documentation that you are reading right now, you can follow the same steps as above. There are helpful links in the top right corner of every page that allow you to quickly edit pages and create issues about them.

3 - Struct Field Comments

How Struct Field Descriptions Work

To be able to read struct field descriptions and use them in the GUI as tooltips, they need to be specified as struct field tags; for example:

type MyStruct struct {
    Field int `desc:"a description"`
}

This has the unfortunate side effect that struct field descriptions are not comments and thus can not be read by editor tools, like the VS Code Go extension. Being able to hover over a field and see its documentation in the editor is incredibly helpful, and it is critical for a good developer experience. As such, we came up with a solution for struct field description comments: a fork of goimports.

The goki/go-tools repository

The goki/go-tools repository is a fork of golang/tools, and it modifies goimports to automatically insert documentation comments for struct fields based on their description tags and other tags. For example, it would change the example struct above to the following:

type MyStruct struct {
    // a description
    Field int `desc:"a description"`
}

We build upon goimports because it is a tool already called in almost all Go editors on save, so it will easily keep struct field comments up to date with no worrying about go generate commands. Any time you add, update, or remove the description for a struct field, the comment will update immediately on save. Also, any changes to the comment will be reverted.

Installation

The struct field comments generated by the tool will be visible in all editors without any extra effort. However, if you are making an app with Goki that uses struct field descriptions or contributing to any of the Goki repositories, you should install the fork of goimports so that you will generate struct field comments. Installation is very simple – you just have to run

go install github.com/goki/go-tools/cmd/goimports@latest

Then, you should configure your editor to run the correct version of goimports. For our Gide editor, there is no more configuration necessary. For VS Code, you should follow these steps:

1. Run which goimports and copy the result, as you will need it later.
   • On Windows, run where goimports in Command Prompt (not Git Bash like other commands) instead.
2. Go to Settings and search for goimports
3. Set Go: Format Tool to custom
4. In the description for Go: Format Tool, click on Go: Alternate Tools
5. Click Edit in settings.json
6. Add a new line under "go.alternateTools": { that says "customFormatter": "{{THE_RESULT_OF_WHICH_GOIMPORTS_THAT_YOU_COPIED}}" (obviously substituting in the thing you copied earlier)
   • On Windows, you need to run change the result of where goimports that you pasted in by adding an extra backslash to each backslash (for example, C:\Users\me\go\bin\goimports.exe would change to C:\\Users\\me\\go\\bin\\goimports)

After you do those steps, the go section of your settings.json should contain the following lines:

"go.formatTool": "custom",
"go.alternateTools": {
    "customFormatter": "{{THE_RESULT_OF_WHICH_GOIMPORTS_THAT_YOU_COPIED}}"
},

For other editors, you should be able to figure out what to do by doing something similar to the steps for VS Code above, looking at the goimports installation directions, and looking for settings related to goimports and Go tools. If you are unable to figure out how to configure your editor to run the correct goimports tool, please create an issue on the goki/go-tools repository.