|
| 1 | +--- |
| 2 | +applyTo: "**" |
| 3 | +--- |
| 4 | + |
| 5 | +# Development Guidelines |
| 6 | + |
| 7 | +This document contains the critical information about working with the project codebase. |
| 8 | +Follows these guidelines precisely to ensure consistency and maintainability of the code. |
| 9 | + |
| 10 | +## Stack |
| 11 | + |
| 12 | +- Language: Go (Go 1.24+) |
| 13 | +- Framework: Go standard library |
| 14 | +- Testing: Go's built-in testing package |
| 15 | +- Build Tool: `make` using the Makefile with all the targets defined to build, test, and run the application |
| 16 | +- Dependency Management: Go modules |
| 17 | +- Version Control: Git |
| 18 | +- Documentation: GoDoc |
| 19 | +- Code Review: Pull requests on GitHub |
| 20 | +- CI/CD: GitHub Actions |
| 21 | +- Database: PostgreSQL |
| 22 | +- Logging: `slog` package from the standard library |
| 23 | + |
| 24 | +## Project Structure |
| 25 | + |
| 26 | +This project implements a kind of Model-View-Controller (MVC) architecture, the main components are: |
| 27 | + |
| 28 | +- Core: located in the `internal/core` package, it contains the business logic of the application. |
| 29 | +- Config: located in the `internal/config` package, it contains the configuration of the application |
| 30 | +- Model: located in the `internal/model` package, it contains the data structures or entities used in the application. |
| 31 | +- Repository: located in the `internal/repository` package, it contains the data access layer for interacting with the database. |
| 32 | +- Identity Provider conversion: located in the `internal/idp/` package, This is the glue between the logic into `internal/core` and the identity provider located at `pkg/google/` package. |
| 33 | +- SCIM conversion: located in the `internal/scim/` package, This is the glue between the logic into `internal/core` and the SCIM API located at `pkg/aws/` package. |
| 34 | + |
| 35 | +The project structure is organized as follows: |
| 36 | + |
| 37 | +```plaintext |
| 38 | +. |
| 39 | +├── build |
| 40 | +│ ├── coverage.txt |
| 41 | +│ ├── idpscim |
| 42 | +│ └── idpscimcli |
| 43 | +├── cmd |
| 44 | +│ ├── idpscim |
| 45 | +│ │ ├── cmd |
| 46 | +│ │ │ └── root.go |
| 47 | +│ │ └── main.go |
| 48 | +│ └── idpscimcli |
| 49 | +│ ├── cmd |
| 50 | +│ │ ├── aws.go |
| 51 | +│ │ ├── common.go |
| 52 | +│ │ ├── gws.go |
| 53 | +│ │ └── root.go |
| 54 | +│ └── main.go |
| 55 | +├── CODE_OF_CONDUCT.md |
| 56 | +├── CONTRIBUTING.md |
| 57 | +├── coverage.out |
| 58 | +├── DCO |
| 59 | +├── Dockerfile |
| 60 | +├── docs |
| 61 | +│ ├── AWS-SAM-Template.md |
| 62 | +│ ├── AWS-SAM.md |
| 63 | +│ ├── Configuration.md |
| 64 | +│ ├── Demo.md |
| 65 | +│ ├── Development.md |
| 66 | +│ ├── idpscim.md |
| 67 | +│ ├── idpscimcli.md |
| 68 | +│ ├── images |
| 69 | +│ │ ├── demo |
| 70 | +│ │ │ ├── aws-groups-developers.png |
| 71 | +│ │ │ ├── aws-groups.png |
| 72 | +│ │ │ ├── aws-s3-state-file.png |
| 73 | +│ │ │ ├── aws-users.png |
| 74 | +│ │ │ ├── gws-groups-developers.png |
| 75 | +│ │ │ ├── gws-groups.png |
| 76 | +│ │ │ ├── gws-users.png |
| 77 | +│ │ │ ├── idpscim-help.png |
| 78 | +│ │ │ ├── state-file.png |
| 79 | +│ │ │ ├── sync-1.png |
| 80 | +│ │ │ └── sync-2.png |
| 81 | +│ │ └── diagrams |
| 82 | +│ │ ├── idpscim--workflow.drawio.html |
| 83 | +│ │ ├── idpscim--workflow.drawio.png |
| 84 | +│ │ └── ipd-scim-sync.drawio.png |
| 85 | +│ ├── Release.md |
| 86 | +│ ├── State-File-example.md |
| 87 | +│ └── Using-SSO.md |
| 88 | +├── extras |
| 89 | +│ └── infra |
| 90 | +│ ├── 1_cfn-slashdevops-iam-oidc-github-provider.template |
| 91 | +│ ├── 2_cfn-slashdevops-iam-role-idp-scim-sync.template |
| 92 | +│ ├── 3_cfn-slashdevops-ecr-repo-idp-scim-sync.template |
| 93 | +│ ├── 4_cfn-slashdevops-iam-policy-idp-scim-sync-ecr.template |
| 94 | +│ ├── 4_cfn-slashdevops-s3-idp-scim-sync-sam.template |
| 95 | +│ ├── 5_cfn-slashdevops-iam-policy-idp-scim-sync-sam.template |
| 96 | +│ └── README.md |
| 97 | +├── go.mod |
| 98 | +├── go.sum |
| 99 | +├── internal |
| 100 | +│ ├── config |
| 101 | +│ ├── core |
| 102 | +│ ├── deepcopy |
| 103 | +│ ├── idp |
| 104 | +│ ├── model |
| 105 | +│ ├── repository |
| 106 | +│ ├── scim |
| 107 | +│ └── version |
| 108 | +├── LICENSE |
| 109 | +├── Makefile |
| 110 | +├── mocks |
| 111 | +├── pkg |
| 112 | +│ ├── aws |
| 113 | +│ └── google |
| 114 | +├── README.md |
| 115 | +├── SECURITY.md |
| 116 | +└── template.yaml |
| 117 | +``` |
| 118 | + |
| 119 | +## Code Style |
| 120 | + |
| 121 | +- Follow Go's idiomatic style defined in |
| 122 | + - [Go Style Guide](https://google.github.io/styleguide/go/guide) |
| 123 | + - [Go Style Decisions](https://google.github.io/styleguide/go/decisions) |
| 124 | + - [Go Style Best Practices](https://google.github.io/styleguide/go/best-practices) |
| 125 | + - [Effective Go](https://golang.org/doc/effective_go.html) |
| 126 | +- Use meaningful names for variables, functions, and packages. |
| 127 | +- Keep functions small and focused on a single task. |
| 128 | +- Use comments to explain complex logic or decisions. |
| 129 | +- Use dependency injection for services and repositories to facilitate testing and maintainability. |
| 130 | + |
| 131 | +## Testing |
| 132 | + |
| 133 | +- Write unit tests implementing test tables for all functions when applicable. |
| 134 | +- Use the `testing` package for writing tests. |
| 135 | +- Use `go test` to run tests. |
| 136 | +- Use `go test -cover` to check code coverage. |
| 137 | +- Use `go test -race` to check for race conditions. |
| 138 | +- Use `go test -bench` to run benchmarks. |
| 139 | +- Use `go test -v` for verbose output during testing. |
| 140 | +- Use `go test -run` to run specific tests. |
| 141 | +- Use `go test -short` to run short tests. |
0 commit comments