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.