refactor: improve contributor experience (#201)

CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# How to contribute
+
+Welcome on the CONTRIBUTING page of asyncapi-codegen ! Thanks for your interest
+in contributing to this project, any contribution/suggestion is warmly welcomed.
+
+If you need further guidance, you can find our team on the following:
+* [Discussions on Github](https://github.com/lerenn/asyncapi-codegen/discussions)
+
+## Contributing
+
+### 1. Create an issue
+
+If you have a suggestion, a bug, or any kind of thing that should impact the
+source code, please open an issue on the
+[Github repository](https://github.com/lerenn/asyncapi-codegen/issues).
+
+Expose your problem and/or the suggestion and feel free to mention if you are
+willing to do the change by yourself or prefer to let someone else do it.
+
+It is important to open an issue in order to discuss the matter and avoid any
+unecessary back-and-forth exchanges that would result in uneeded change in
+the code you would write. 
+
+### 2. Write your contribution
+
+#### Start the development environment
+
+If and once you're ready to write the contribution, you can start the development
+environment by typing this command:
+
+```bash 
+make dev/up
+```
+
+Once you're done, you can terminate your environment by typing this command:
+
+```bash
+make dev/down
+```
+
+#### Explore the source code
+
+Code is separated between the following directories:
+* `build/` contains the files related to the CI and the packaging (Docker, ...)
+  of asyncapi-codegen project
+* `cmd/` contains all executable produces by this project (no the project
+  internal tools)
+* `examples/` contains workable examples of generated code along to their asyncapi
+  document against the brokers supported in this project. You can test them if
+  you start the `app` in a terminal then the `user` in another by using
+  `go run ./examples/<example>/v<version>/<broker>/<app|user>`
+* `pkg/`contains all the project source code that can be reused in other projects:
+    * `pkg/asyncapi` contains the Go code for asyncapi specification
+    * `pkg/ci` contains the Go code for the CI
+    * `pkg/codegen` contains the Go code for the code generation
+    * `pkg/extensions` contains the Go code for the extensions used by asyncapi-codegen users
+    * `pkg/utils` contains the Go code for the utilities used by asyncapi-codegen
+* `tests/` contains the tests of the project by version and by type (issue, etc).
+  This is where you should implement your tests linked to your issues if this implies
+  code generation.
+* `tools/` contains the tools used by the project (like the certs generation tool
+  for testing)
+
+#### Write your code
+
+Once you've explored the source code, you can start writing your code.
+
+Please follow the following rules:
+* Write tests for your code if possible
+* Respect the code style (linter)
+
+#### Test your code
+
+##### Without code generation
+
+If you don't need code generation (testing broker implementation, asyncapi
+parsing, etc), feel free to add tests close to your changes in a `*_test.go` file.
+
+##### With code generation
+
+If you're code implies some code generation, you can write test in the corresponding
+directory `./test/<version>/issue<#>/` where you can put the following files:
+* `asyncapi.yml` the asyncapi document that will be used to generate the code
+* `asyncapi.gen.go` the generated code
+* `suite_test.go` the test file that will be used to test the generated code, it
+  should have a `//go:generate` command to generate the `asyncapi.gen.go`.
+
+Please respect the following rules:
+* Channels should be prefixed with the version and the issue number (example:
+  `v2.issue1`) to avoid collision in case of parallel tests
+* The test package should be named `issue<#>` where `#` is the issue number
+* Use the testify framework to write your tests (see the existing tests for
+  examples)
+* Brokers from `test/brokers.go` should be used to ensure that tests works with
+  all brokers.
+
+Of course, do not hesitate to ask for help if you need it.
+
+### 3. Open a pull request
+
+Once you're done with your code, you can open a pull request on the
+[Github repository](https://github.com/lerenn/asyncapi-codegen/pulls).
+
+## Missing information here?
+
+If you think that some information is missing here, feel free to open an issue
+on the [Github repository](https://github.com/lerenn/asyncapi-codegen/issues).

CONTRIBUTORS.md

@@ -0,0 +1,23 @@
+# Contributors
+
+This is maybe the most important file of this project: it recognizes people who
+are helping and are, directly or indirectly, baking this project success.
+
+Those people spend their time, for free, to make this project better. As time is an
+asset that never comes back, and these people choose to use their time in this
+adventure, this file is a attempt to show them the respect they earned.
+
+## Special thanks for all the people who have helped this project so far
+
+* [Mario Graef (@magraef)](https://github.com/magraef)
+* [Sergey Kostyuchenko (@derfenix)](https://github.com/derfenix)
+* [Matouš Dzivjak (@matoous)](https://github.com/matoous)
+* [Olivier Bouchet (@obouchet)](https://github.com/obouchet)
+* [Tzu-Yu Lee (@leejuyuu)](https://github.com/leejuyuu)
+* [Stefan Meschke (@stefanmeschke)](https://github.com/stefanmeschke)
+* [Aleksey (@lo00l)](https://github.com/lo00l)
+* And maybe you ?
+
+## I would like to join the list. How can I help the project?
+
+For more information, please refer to our [CONTRIBUTING](./CONTRIBUTING.md) guide.

Makefile

@@ -4,36 +4,49 @@ ifndef EXAMPLE
 	EXAMPLE=""
 endif
 
-ifndef TEST
-	TEST=""
-endif
-
 ifndef TAG
 	TAG=""
 endif
 
+.PHONY: all
+all: generate lint examples test ## Run all the checks
+
 .PHONY: ci
 ci: ## Run the CI
 	@${DAGGER_COMMAND} all
 
+.PHONY: clean
+clean: dev/down ## Clean the project
+	@rm -rf ./tmp/certs
+
+.PHONY: dev/up
+dev/up: ## Start the development environment
+	@go run ./tools/generate-certs
+	@docker-compose up -d
+
+.PHONY: dev/down
+dev/down: ## Stop the development environment
+	@docker-compose down
+
 .PHONY: lint
 lint: ## Lint the code
-	@${DAGGER_COMMAND} linter
+	@go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55 run ./...
 
 .PHONY: examples
 examples: ## Perform examples
 	@${DAGGER_COMMAND} examples -e ${EXAMPLE}
 
 .PHONY: test
-test: ## Perform tests
-	@${DAGGER_COMMAND} test -t ${TEST}
+test: dev/up ## Perform tests
+	@go test ./...
 
 .PHONY: generate
 generate: ## Generate files
-	@${DAGGER_COMMAND} generator
+	@go generate ./...
 
 .PHONY: publish
 publish: ## Publish with tag on git, docker hub, etc.
+	@git tag ${TAG} && git push origin ${TAG}
 	@${DAGGER_COMMAND} publish --tag ${TAG}
 
 .PHONY: help

build/ci/dagger.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"os"
-	"strings"
 	"sync"
 
 	"dagger.io/dagger"
@@ -21,11 +20,6 @@ var (
 	testFlag    string
 
 	brokers map[string]*dagger.Service
-
-	generator func(context.Context) error
-	linter    *dagger.Container
-	examples  map[string]*dagger.Container
-	tests     map[string]*dagger.Container
 )
 
 var rootCmd = &cobra.Command{
@@ -42,12 +36,6 @@ var rootCmd = &cobra.Command{
 		// Create services
 		brokers = ci.Brokers(client)
 
-		// Create containers
-		generator = ci.Generator(client)
-		linter = ci.Linter(client)
-		examples = ci.Examples(client, brokers)
-		tests = ci.Tests(client, brokers)
-
 		return nil
 	},
 }
@@ -57,9 +45,10 @@ var allCmd = &cobra.Command{
 	Aliases: []string{"a"},
 	Short:   "Execute all CI",
 	Run: func(cmd *cobra.Command, args []string) {
-		execute(context.Background(), generator)
-		executeContainers(context.Background(), []*dagger.Container{linter})
-		executeContainers(context.Background(), utils.MapToList(tests), utils.MapToList(examples))
+		execute(context.Background(), ci.Generator(client))
+		executeContainers(context.Background(), ci.Linter(client))
+		executeContainers(context.Background(), ci.Tests(client, brokers, "./..."))
+		executeContainers(context.Background(), ci.Tests(client, brokers, "./..."))
 	},
 }
 
@@ -68,14 +57,16 @@ var examplesCmd = &cobra.Command{
 	Aliases: []string{"g"},
 	Short:   "Execute examples step of the CI",
 	Run: func(cmd *cobra.Command, args []string) {
+		examples := ci.Examples(client, brokers)
+
 		if exampleFlag != "" {
 			_, exists := examples[exampleFlag]
 			if !exists {
 				panic(fmt.Errorf("example %q doesn't exist", exampleFlag))
 			}
-			executeContainers(context.Background(), []*dagger.Container{examples[exampleFlag]})
+			executeContainers(context.Background(), examples[exampleFlag])
 		} else {
-			executeContainers(context.Background(), utils.MapToList(examples))
+			executeContainers(context.Background(), utils.MapToList(examples)...)
 		}
 	},
 }
@@ -85,7 +76,7 @@ var generatorCmd = &cobra.Command{
 	Aliases: []string{"g"},
 	Short:   "Execute generator step of the CI",
 	Run: func(cmd *cobra.Command, args []string) {
-		execute(context.Background(), generator)
+		execute(context.Background(), ci.Generator(client))
 	},
 }
 
@@ -94,7 +85,7 @@ var linterCmd = &cobra.Command{
 	Aliases: []string{"g"},
 	Short:   "Execute linter step of the CI",
 	Run: func(cmd *cobra.Command, args []string) {
-		executeContainers(context.Background(), []*dagger.Container{linter})
+		executeContainers(context.Background(), ci.Linter(client))
 	},
 }
 
@@ -112,19 +103,11 @@ var testCmd = &cobra.Command{
 	Aliases: []string{"g"},
 	Short:   "Execute tests step of the CI",
 	Run: func(cmd *cobra.Command, args []string) {
-		if testFlag != "" {
-			if !strings.HasPrefix(testFlag, "./") {
-				testFlag = "./" + testFlag
-			}
-
-			_, exists := tests[testFlag]
-			if !exists {
-				panic(fmt.Errorf("test %q doesn't exist in %+v", testFlag, tests))
-			}
-			executeContainers(context.Background(), []*dagger.Container{tests[testFlag]})
-		} else {
-			executeContainers(context.Background(), utils.MapToList(tests))
+		if testFlag == "" {
+			testFlag = "./..."
 		}
+
+		executeContainers(context.Background(), ci.Tests(client, brokers, testFlag))
 	},
 }
 
@@ -150,24 +133,22 @@ func main() {
 	}
 }
 
-func executeContainers(ctx context.Context, containers ...[]*dagger.Container) {
+func executeContainers(ctx context.Context, containers ...*dagger.Container) {
 	// Regroup arg
 	funcs := make([]func(context.Context) error, 0)
 	for _, l1 := range containers {
-		for _, l2 := range l1 {
-			if l2 == nil {
-				continue
-			}
+		if l1 == nil {
+			continue
+		}
 
-			// Note: create a new local variable to store value of actual l2
-			callback := l2
+		// Note: create a new local variable to store value of actual l2
+		callback := l1
 
-			fn := func(ctx context.Context) error {
-				_, err := callback.Stderr(ctx)
-				return err
-			}
-			funcs = append(funcs, fn)
+		fn := func(ctx context.Context) error {
+			_, err := callback.Stderr(ctx)
+			return err
 		}
+		funcs = append(funcs, fn)
 	}
 
 	execute(ctx, funcs...)