eintopf.info@v0.13.16/CONTRIBUTING.md (about) 1 # Contributing to eintopf 2 3 ## Quick Start 4 5 First you need to install [go](https://golang.org/doc/install) for the api and 6 [yarn](https://classic.yarnpkg.com/lang/en/docs/install/) for the web. 7 8 Development helpers can be found in the `Makefile` located at the project root. 9 In order to get started check out the targets below: 10 11 * `make help` Show all make targets 12 * `make all` Downloads deps, build and test the project 13 14 If `make all` succeeds your development environment should be setup correctly 15 16 ## Project Layout 17 18 This shows the incomplete project structure, describing the most important 19 directories: 20 21 ```text 22 ├─ api/ api swagger specification 23 ├─ cmd/ go binaries 24 │ └─ eintopf/ monolithic binary, serves the api and web frontend 25 ├─ internal/ internal go packages 26 │ ├─ cache/ generic cache library 27 │ ├─ mock/ contains all mocked interfaces (used for testing) 28 │ ├─ xerror/ custom error types 29 │ ├─ xhttp/ provides helper functions for the http transport layer 30 │ └─ xhttptest/ provides helper functions to test the http transport layer 31 ├─ service/ go services 32 │ ├─ api/ api gateway service 33 │ ├─ auth/ authentication service (via JWT) 34 │ ├─ event/ handles the event model 35 │ ├─ eventsearch/ search api for events, based on the search service 36 │ ├─ group/ handles the group model 37 │ ├─ indexo/ operates in an oqueue to index models into a search index 38 │ ├─ invitation/ provides invitations for the user model 39 │ ├─ killswitch/ provides a killswitch to shutdown the api 40 │ ├─ oqueue/ a model operation queue, that can be subscribed to 41 │ ├─ passwordrec/ a password recovery service for the user model 42 │ ├─ place/ handles the place model 43 │ ├─ revent/ handles the repeating event model 44 │ ├─ search/ search service 45 │ ├─ status/ provides information about the status of the api 46 │ └─ user/ handles the user model 47 ├─ scripts/ misc scripts 48 ├─ test/ integration and e2e tests 49 │ ├─ e2e/ e2e tests using cypress 50 │ └─ integration/ integration tests 51 └─ web/ preact frontend 52 └─ src/ 53 ├─ api/ api client 54 ├─ assets/ images, ... 55 ├─ components/ frontend components 56 ├─ hooks/ react hooks 57 ├─ pages/ frontend pages 58 ├─ searchStore/ session storage for search requests 59 ├─ store/ local storage for login information etc. 60 ├─ testing/ testing utilities 61 └─ utils/ random utilities 62 ``` 63 64 ### Environment 65 66 There is a preset environment for development in the `flake.nix` file. To use this preset you need to install 67 direnv with flakes support. A tutorial can be found at the [direnv repo](https://github.com/direnv/direnv/wiki/Nix). 68 The preset was tested with `nix-direnv`. 69 After that run the following command to allow direnv for this folder. 70 ```shell 71 direnv allow 72 ``` 73 74 ### Developing 75 76 ```shell 77 make watch-api 78 make watch-web 79 ``` 80 81 This will start file watchers for the go api and the preact frontend. 82 83 ### Running tests 84 85 ```shell 86 make test 87 ``` 88 89 Will run api and web tests. 90 91 ### Api tests 92 93 ```shell 94 make test-api 95 ``` 96 97 Will run api tests. 98 99 ### Web tests 100 101 ```shell 102 make test-web 103 ``` 104 105 ### Updating Dependencies 106 107 Updating the go version: 108 109 ``` 110 go mod edit -go=1.20 111 ``` 112 113 List all dependencies and their latest version: 114 ``` 115 go list -m -u -f '{{if not .Indirect}}{{.Path}} {{.Version}} {{ with .Update}} -> {{.Version}}{{end}}{{end}}' all 116 ``` 117 118 Update each dependency with an update available: 119 120 ``` 121 go get -u <dep> 122 ``` 123 124 After regenerate files and run tests: 125 126 ``` 127 make generate 128 make test 129 ``` 130 131 ### Debugging Performance 132 133 You can enable the [pprof profiler](https://pkg.go.dev/net/http/pprof) by setting `EINTOPF_DEBUG` to `true`. 134 135 Then run: 136 ```sh 137 go tool pprof http://localhost:3333/debug/pprof/profile?seconds=30 138 ``` 139 140 ### Iconset 141 142 The following icon set is used: [Kalai Oval Interface Icons](https://www.svgrepo.com/collection/kalai-oval-interface-icons/) 143 Please use icons from this set, or a similar style if no fitting icon is available.