github.com/esnet/gdg@v0.6.1-0.20240412190737-6b6eba9c14d8/website/content/docs/developer/contributing.md (about)

     1  ---
     2  title: "Contributing"
     3  weight: 2
     4  ---
     5  
     6  First of all, gdg contains two binaries.  `gdg` which manages grafana entities and provide some tooling facilities
     7  and `gdg-generate` a tool to help generate dashboards from templates to allow for some more flexible management.
     8  gdg-generate is fairly new, but the same quality of PRs would be nice to have.
     9  
    10  ## GDG
    11  
    12  There two types of features that get added to gdg, a `tool` or `backup` feature.
    13  
    14  ### Backup Feature
    15  
    16  A backup feature is some entity that you want to add to GDG that it will track.
    17  
    18  For example, if you want to add support for managing a playlist.
    19  
    20  Typically, we want to be able to:
    21  
    22  1. List all entities in the current namespace (or Org)
    23  2. Download all entities
    24  3. Upload all entities
    25  
    26  In order to add a new feature you will need to:
    27  
    28  0. Create an issue to track this work and explain the feature being added/requested.
    29  1. Create a new CLI subcommand for playlist. under the backup command.
    30  2. Extend the service to be able to list/download/upload etc the entities.
    31  3. Write a unit test for the given entities. If need be add some seed data under test/data/
    32  4. Update the documentation accordingly to reflect the new changes. All docs live under
    33     the [website/content](https://github.com/esnet/gdg/tree/master/website/content/docs). All files are in markdown. If
    34     you wish you can load the website locally by running: `npm install && hugo serve`
    35  
    36  #### Testing
    37  
    38  There are multiple types of tests.
    39  
    40  1. `Integration tests`.  The most common one, an instance of grafana will be available and will connect to it to create/update/delete entities.
    41  2. Unit tests can be created for any unit of work, and will always be executed.
    42  3. CLI tooling tests.  use `task mocks` to generate mocks for your tests.  The purpose of this test is to validate the CLI parsing behavior rather than the service functionality.  Ensure that filtering works, stdout is redirected to the test and can validate the output matches the expectations.
    43  
    44  ### Tools Feature
    45  
    46  This area is more about managing grafana entities.  The tools would provide way for creating service accounts, listing tokens, adding user to orgs, etc.
    47  
    48  Testing such features can be a bit more difficult, but we can see enough data to validate the behavior that's always great and makes for a much more stable feature long term.
    49  
    50  ### Enterprise features
    51  
    52  {{< callout context="caution" title="Caution" icon="alert-triangle" >}}
    53  There are a few enterprise features that GDG supports, but unfortunately as there is no enterprise version we can access in CICD testing is very limited.
    54  {{< /callout >}}