add example for compose and send commands

README.md

@@ -20,7 +20,7 @@
 
 Simple and easy-to-use tool to generate PKUP (`Podwyższone Koszty Uzyskania Przychodu` - Polish law thing) report (`.docx`) and artifacts (`.diff`).
 
-The `pkup-gen` collects all users' commits pushed between the 18th (23:59:59) of the actual month and the 19th (00:00:00) of the past one. To qualify commit, the user should be an author or co-author of it.
+The `pkup-gen` collects all users' commits pushed between the 18th (23:59:59) of the actual month and the 19th (00:00:00) of the past one. To qualify a commit, the user should be an author or co-author of it.
 
 ## Installation
 
@@ -51,16 +51,16 @@ For more go to the [examples](https://github.com/pPrecel/pkup-gen/tree/main/exam
 
 ## report
 
-By default the `pkup-gen` generates the `report.txt` files with all info needed to fill true report.
+By default, the `pkup-gen` generates the `report.txt` files with all the info needed to fill a true report.
 
-The `.docx` report template can be specified  using the `--template` flag. The `pkup-gen` will replace any repeat of the following key-words with the true data:
+The `.docx` report template can be specified using the `--template` flag. The `pkup-gen` will replace any repeat of the following keywords with the true data:
 
 * `pkupGenPeriodFrom` - date of the first day for the actual period
 * `pkupGenPeriodTill` - date of the last day for the actual period
 * `pkupGenApprovalDate` - date of the last day of the period plus one day
 * `pkupGenResults` - list of all PullRequests if format <PR_TITLE>( DIFF_FILE_NAME )
 
-The `pkup-gen` allows to add new formula to replace in the output `.docx` file. It can be achieved by adding flag `--report-field` like in the following example:
+The `pkup-gen` allows adding a new formula to replace the output `.docx` file. It can be achieved by adding a flag `--report-field` like in the following example:
 
 ```bash
 --report-field "pkupGenEmployeesName=John Wick"
@@ -70,6 +70,12 @@ The `pkup-gen` allows to add new formula to replace in the output `.docx` file.
 
 The `pkup-gen` needs credentials to connect with the GitHub API. There are two possible ways to pass such credentials:
 
-* By default the `pkup-gen` will reach the [pkup-gen](https://github.com/apps/pkup-gen) app using the GitHub device API. The generated token will be saved on local machine so next time, until the token expires, user will be logged in. This flow is not working with the `--enterprise-url` flag.
+* By default, the `pkup-gen` will reach the [pkup-gen](https://github.com/apps/pkup-gen) app using the GitHub device API. The generated token will be saved on the local machine so next time, until the token expires, the user will be logged in. This flow is not working with the `--enterprise-url` flag.
 
 * The `--token` flag allows to pass a [PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). For public projects, the generated token does not need to have any permissions.
+
+## Automation
+
+The `pkup-gen` application supports more complex use cases to generate a report based on several different GitHub instances ( for example opensource and enterprise ) and for many usernames. The app allows one to compose many reports for the same orgs/repos for many people and send emails to them with zipped reports.
+
+For more read [this](./examples/compose-and-send/README.md) article.

examples/compose-and-send/README.md

@@ -0,0 +1,61 @@
+# Compose and Send
+
+This scenario describes how to generate many reports for given repositories and organizations and send them to developers.
+
+> NOTE: knowledge from the [simple-scenario](../simple-flow/README.md) and the [with-template](../with-template/README.md) may be useful to clarify some topics.
+
+1. Create the `.pkupgencompose.yaml` file with the whole configuration ( config details [here](../../pkg/config/config.go) ):
+
+    ```yaml
+    reports:
+    - outputDir: reports/FILIP_STROZIK
+      email: "filip.strozik@outlook.com"
+      signatures:
+      - username: pPrecel
+      - username: internalPrecel
+        enterpriseUrl: "https://github.my-corp"
+      reportFields:
+        pkupGenEmployeesName: "Filip Strózik"
+        pkupGenJobTitle: "Senior Developer"
+        pkupGenDepartment: "R&D"
+        pkupGenManagersName: "John Wick"
+    # - outputDir: ...
+
+    template: templates/report.docx
+
+    orgs:
+    - name: kyma-project
+      token: ghp_5...C
+    - name: kyma-incubator
+      token: ghp_5...C
+    - name: kyma
+      token: ghp_1...G
+      enterpriseUrl: "https://github.my-corp"
+
+    repos:
+    - name: kyma-project/busola
+      token: ghp_5...C
+      allBranches: true
+      uniqueOnly: true
+    - name: kyma-project/cli
+      token: ghp_5...C
+      branches: ["main", "v3"]
+      uniqueOnly: true
+
+    send:
+      serverAddress: "smtp-mail.outlook.com"
+      serverPort: 587
+      username: "filip.strozik@outlook.com"
+      password: *************
+      subject: "PKUP report"
+      htmlBodyPath: "templates/email_body_template.html"
+      from: filip.strozik@outlook.com
+    ```
+
+2. Compose report ( example output ):
+
+    ![1](../../assets/screenshot-compose-and-send-1.png)
+
+3. Send email ( example output ):
+
+    ![2](../../assets/screenshot-compose-and-send-2.png)

examples/simple-flow/README.md

@@ -12,7 +12,8 @@ This scenario shows how to generate `.diff` files for a few repositories for the
 
 2. Because PAT is not provided, `pkup-gen` tries to connect to the GitHub app to create one - here follow the instructions in the `WARN` log:
 
-    ![1]On the GitHub side you have to pass the copied code, click `Continue` and then `Authorize pkup-gen`:
+    ![1](../../assets/screenshot-simple-flow-1.png)
+    On the GitHub side, you have to pass the copied code, click `Continue` and then `Authorize pkup-gen`:
     ![2](../../assets/screenshot-simple-flow-2.png)
     ![3](../../assets/screenshot-simple-flow-3.png)
 

pkg/config/config.go

@@ -11,6 +11,7 @@ type Config struct {
 	// path to the report template
 	Template string `yaml:"template"`
 	// repos based on which report will be generated ( with name in format <ORG>/<REPO> )
+	// can override orgs config for a specific repo
 	Repos []Remote `yaml:"repos,omitempty"`
 	// orgs based on which report will be generated ( with name in format <ORG> )
 	Orgs []Remote `yaml:"orgs,omitempty"`