issue_generator/README.md

# Updates issue generator

A project to turn RSS update feeds into new issues in the projects that depend on them.

## Usage

Create a file called `config.py`, which should contain a list `FEED_READERS`. The
list should contain one or more feed readers (`issue_generator.FeedReader`), which
in turn contain an issue poster (`issue_generator.IssuePoster`).

The reader will check up on the RSS feed and compare against a local folder with the
last version of the software it saw (stored at `~/.config/issue_generator` or
`$XDG_CONFIG_DIR/issue_generator` by default). Then, if the version differs (it doesn't
sort them, just compare equality), it opens an issue with the corresponding issue poster.
Currently, there is duplicate issue detection, to avoid posting duplicate issues when
the config is cleared (e.g. running in a different machine).

See the documentation of each feed reader and issue poster with `import issue_generator`,
`help(issue_generator)` to see how each parameter works.

## Example configuration files

Read the `config.py` file, which requires a `_secrets.py` file (which you should write).
It uses the readers and posters defined in `issue_generator` to create an array of
readers. Below there are examples with three levels of complexity.

Simple example: use the available readers/posters.
```python
from issue_generator import GithubReader, GitlabPoster

FEED_READERS = [
    # Post an issue on Gitlab.com for new releases of Gitea
    GithubReader(name    = "gitea",
                 project = "gitea-go/gitea",
                 target  = GitlabPoster(project = 65536, # your project id here
                                        token   = "qwerty-secret-token"))
]
```

Intermediate example: the class `CGJForgejoPoster` in `config.py` acts as a shortcut
for any project hosted in the organization `archpkgs` in `git.cgj.es/`. Because the
token, the instance and assignee/labels are the same, the user of this poster can simply
indicate the repository to use it.

Complex example: the class `UDSClientReader` is a custom reader for a piece of software
that doesn't publish a feed. Instead, this reader scraps the version out of a JavaScript
file.