goadesign / goa.design

Public website for goa

goa.design

This repository contains the source code of https://goa.design. The site is a static website built using hugo.

Contributing

Is that typo bugging you? us too! If you want to do something about it:

1. Fork and clone the repo
2. Open a terminal, cd into the cloned repo and run make
3. Edit the content of the markdown files in the /content directory.
4. Submit a Pull Request

make starts a server on your box that "live-loads" all changes you make to the content (that is the page should refresh itself each time you save a content page). Once make complete simply open a browser to http://localhost:1313 and browse to the page you are editing.

Run the documentation using Docker without having to install Go

Run in a terminal:

cd goa.design;
docker run --name goadocs --volume .:/go/src/app -p 1313:1313 -it golang:1.21.2 bash;
# in the container:
cd /go/src/app;
make;

To run the container in the future:

docker start goadocs;
docker exec -it goadocs bash;
cd /go/src/app;

To remove the container:

docker stop goadocs;
docker rm goadocs;
docker rmi golang:1.21.2;

Translations

Translations are kept under the content directory. Each language has its own file extension of the form <code>.md where <code> is the ISO 2 letter language code.

To contribute to an existing translation:

1. Fork and Clone the repo.
2. Checkout the language specific branch (named after the language code).
3. Make your changes in the branch in content/<code>.
4. Send Pull Requests to the branch.
5. When the translation is ready send a PR to the master branch.

To start a new translation:

1. Open a new issue describing the new language being translated to
2. Figure out your language code. For example: ja, zh, es, de, ...etc.
3. A team member will make a new branch. For example fr or ja.
4. Fork the branch and add the required files, see below.
5. Send PRs to the branch (this can be work in progress).
6. When the translation is ready send a PR to the master branch.

The files that support a given language are:

• layouts/<code>/: contains the layout pages
• layouts/partials/<code>/: contains the partials files

goa.design's Issues

Broken Link in API Documentation

https://goa.design/reference/goa/design/apidsl/#func-routing-a-name-apidsl-routing-a

Clicking "httptreemux" retuns 404

Add proper multilingual support

See https://github.com/spf13/hugo/blob/d8c372cad52c44f76943f8c5592dc02a1eb65409/docs/content/content/multilingual.md

Italian Translation

I am going to take care of the italian translation of the website

Translate new "Implementing a Goa Service"

@tchssk @ikawaha I added a new page https://goa.design/ja/implement/implementing/ and need help for the Japanese translation :)

Thank you!

Broken link from https://goa.design/learn/getting-started/

Near the bottom "design overview" links to missing https://goa.design/learn/design/overview

Fix JavaScript search index

Currently it points to obsolete files.

Navigate control is very slow

On android the navigate control , when pressed, delays for 1 or 2 seconds, before opening up a list from which the user can see the page names.

I like the way it works because it's not using side bars and other semi confusing GUI techniques.
But the 1 or 2 second delay made me think something was broken, and it's really disconcerting.

Got error generate gorma/design

When i run

$ goagen --design=gorma/design gen --pkg-path=gorma/design

I got

../github.com/goadesign/gorma/relationalmodel.go:9:2: cannot find package "bitbucket.org/pkg/inflect" in any of:
/usr/local/go/src/bitbucket.org/pkg/inflect (from $GOROOT)

Do you have solution?

Links to URLs in the apidsl reference document are rendered wrong

Hi,

I noticed that the links to external URLs in the API DSL reference document do not work, e.g. https://goa.design/reference/goa/design/apidsl/#func-oauth2security-a-name-apidsl-oauth2security-a contains the following HTML:

<a href="a href=&quot;https://aaronparecki.com/2012/07/29/2/oauth2-simplified&quot;&gt;https://aaronparecki.com/2012/07/29/2/oauth2-simplified&lt;/a">Aaron Parecki’s
writeup</a>

(Note the extra a href= in the href attribute)

Documentation link is dead

I found a dead link on the Goa website. To reproduce:

1. Follow this link https://goa.design/reference/goa/design/apidsl/#func-oauth2security-a-name-apidsl-oauth2security-a

2. Click the link to Aaron Parecki's blog post.

Note: the URL bar is in Chinese (Japanese?), the Sad Gopher link is broken, and the URL is wacky.

Here's a copy of my URL:
https://goa.design/reference/goa/design/apidsl/a%20href=%22https:/aaronparecki.com/2012/07/29/2/oauth2-simplified%22%3Ehttps:/aaronparecki.com/2012/07/29/2/oauth2-simplified%3C/a

As you can see, the intended URL is concatenated with the base for the application. Assumedly, the intended URL was "https:/aaronparecki.com/2012/07/29/2/oauth2-simplified" but it's prefaced with the API base URL ("https://goa.design/reference/goa/design/apidsl").

Add 404 page.

Come up with witty content.

Response ArrayOf validation errors.

Add section on CORS

Fix broken reference

When built from commit to other repos.

Cleanup obsolete files

Using the old ".html" links still works but shouldn't.

GOPATH is confusing - can we clarify in tutorials a little?

so I think I have some sort of new error or at least I can’t find it
[9:04 PM]
I’m just following the tutorial from goa.design
new messages
[9:08 PM]
I create the directory for my code under $GOPATH/src/cellar
I cd into that directory
I put the example code under design/design.go
when I run goagen bootstrap -d design/design.go , I get the error:

/Users/jeremywhite/Code/go/src/design/design does not contain the design/design Go package

Now I know all I need to do is change this command to goadesign bootstrap -d cellar/design and all is well… but this would confuse a newbie.
[9:08 PM]
so I think that might need a tweak in the docs, but maybe someone already saw this? it seems like an easy thing to find… so wanted other folks thoughts

Add links from reference functions to source code

A la Godoc

Missing Italian translations

@saniales I need help translating https://goa.design/it/implement/implementing/ into Italian :)

Also I noticed that https://goa.design/it/implement/error_handling wasn't translated (I just added the file - it was missing entirely).

Invalid code snippet of the DSL roots

Hello to All!

Extending goa with Plugin DSLs contains the invalid snippet in the section The DSL Roots. Look the diff below:

package modeldsl

// Root is the data structure built by the DSL.
type Root struct {
	Models []*ModelDefinition
	Types []*TypeDefinition
}

// dslRoot contains the instance of Root built by the DSL
var dslRoot = &Root{}

// IterateSets first returns the type definitions then the model definitions.
func (r *Root) IterateSets(it dslengine.SetIterator) {
-	err := it(r.Types)
+	var types dslengine.DefinitionSet
+	for _, v := range r.Types {
+		types = append(types, v)
+	}
+	err := it(types)
	if err != nil {
		return // The errors will be reported to the user by the DSL engine.
	}
-	it(r.Models)
+	
+	var models dslengine.DefintionSet
+	for _, v := range r.Models {
+		models = append(models, v)
+	}
+	it(models)
}

Thanks

Broken Doc Link for httptreemux

https://goa.design/reference/goa/design/apidsl/#func-routing-a-name-apidsl-routing-a has a reference under the Routing description to httptreemux that doesn't resolve.

The tree mux hyperlink references: https://goa.design/reference/goa/design/apidsl/a%20href=%22https://godoc.org/github.com/dimfeld/httptreemux%22%3Ehttps://godoc.org/github.com/dimfeld/httptreemux%3C/a

broken link

broken link to "APIDefinition" on https://goa.design/extend/generators/

Add sections on security

Add sections to both the "Design" and "Implement" contents describing the security support built into goa. Add header comments to all DSL functions that contain examples that show all the possible syntax for the generated "Reference".

The design section should focus on describing the abstractions and the DSL with examples. It should also explain the effects on the generated code.

The implement section should explain how to provide a "config" function, where it fits, what it should do etc.

If time allows it would be great for the docs to refer to examples from the examples repo. The idea for these is to be small in scope and to showcase specific functionality (e.g. an example to showcase JWT, another one for oauth2 etc.).

Missing page "Working with Data Types"

My data structures require int64 fields, but using Goa's "Integer" type in the design.go file means everything is getting dumbed down to an int.

In trying to find a way around this, I searched the goa docs and clicked on the topic "Working with Data Types" which leads to a 404 error.

Figure out caching issue

When new docs are generated it seems the appengine memcache needs to be cleared manually before they are live.

Add the ability to validate arrays and collections of items

[v3] Generated code points to obsolete documentation

The generated v3 code in cmd/svc/http.go says to check goa.design/encoding for reference, however it no longer exists.