briggysmalls / gisrep Goto Github PK

Currently if the credentials need updating the only option is to use gisrep init --force.
However this will obliterate any existing config.
The semantics of 'init' would indicate that this is correct, but it is also annoying to lose any template directories that have been added in the even you entered your password wrong/token expired.

The project should be able to be developed by the open source community. To do so, some of the following might be necessary:

• Add linter
• Add CONTRIBUTING.md /.rst
• Define testing strategy

The tool creates the .gisreprc file in the home directory, and adds a password to the password manager.

These things should be cleaned up if the package is uninstalled.

• There should be an explanation that you need a Github personal auth token in place of password for private repositories
• There should be an option to specify a config file via the command line
• There should be an option to pass credentials via the command line

The project is missing the following fundamental project requirements:

• Create README
• Create licence
• Add long_description

In order to nicely test the tool, a different keyring backend should be chosen for test completeness (it is proving very difficult to use dbus/gnome-keyring on travis/headless systems - despite getting very close)

It should also be confirmed that non-headless Linux systems can use keyring fine. I got close on an Ubuntu VM following the relevant section in the keyring README.

Currently the software uses the RuntimeError exception for all failures. This could be replaced with some custom errors, e.g.:

• GisrepError

Furthermore the stack trace is listed, which is fairly confusing, rather than displaying to the user the correct CLI action to take (e.g. run gisrep init)

After playing with the jinja2 I realise it is pretty powerful.

Using macros and calls, repeated logic (e.g. filters on for loops) can be made reusable, giving a lot of power to manipulate the issues handed to the template.

It is also possible to map, select, groupby attributes etc.

The complexity of the tool is far reduced if the 'look for python file with same name' feature is removed The addition of custom templates is made simpler too.

In the interest of not needing to keep documentation up to date with the code, the tool should have documentation generated from argparse, using something like sphinx-argparse

It is too easy to add features and not update tests appropriately.

A coverage checker should be integrated with Github

Currently the format command can be executed using tox, however it is not run on the CI server.

Format should be run and any differences in the source should cause the build to fail

Currently modules, functions and classes are all missing documentation.
These should be added (and required/enforced by the linter #2)

Templates will appear differently based upon the jinja2 environment configuration.

For example, trim_blocks may or may not be desireable. Furthermore a template might benefit from the do statement introduced by the jinja2.ext.do extension.

A CLI option could be added to pass some kind of configuration to the jinja2 environment object created.

I'm still not happy with the CLI. I am now thinking:

• Query: positional argument. Required.
• Template: Named argument. Optional. Defaults to simple_report.md
• Output: Named argument. Optional. Defaults to stdout

gisrep report [-h] query [--template TEMPLATE [TEMPLATE ...]] [--output OUTPUT [OUTPUT ...]]

I do think there is still an issue with how the help text is printed for multi-argument(s) for output (and potentially templates). It makes it look like multiple OUTPUTs can be provided, when it might make more sense to show something like:

gisrep report [-h] query [--template TEMPLATE [T-ARG-1 ...]] [--output OUTPUT [O-ARG-1 ...]]

Perhaps this can be done with some configuration of argparse.

The search API for issues takes three parameters:

• q (query)
• sort
• order

Currently only the query can be provided by the user on the CLI, and passed to PyGithub. The sort and order options should be added too.

Currently the templates and outputs submodules contain the bundled templates and outputs. However the design was to allow a user to add their own externally-defined custom templates/outputs.

This approach should be implemented via the CLI and tested. This might either allow a user to specify a path of a template/output instance as an argument to the report command, or alternatively a directory could be added using the templates or outputs command.

Currently the MANIFEST.in refers to LICENSE.txt when in fact the file is called LICENSE.

The more I think about it, the less I feel it is gisrep's responsibility to offer different outputs. A command line tool should do one thing well. Thus gisrep should:

• fetch issues
• format them nicely
• print them out

You can save to a file easily on many OSs:

gisrep report simple_report.md "repo:twbs/bootstrap is:open label:feature" > myfile.md

On macOS you can copy to the clipboard with pbcopy:

gisrep report simple_report.md "repo:twbs/bootstrap is:open label:feature" | pbcopy

Is it reasonable to want to define everything in setup.cfg? This is forcing a very new version of setuptools on anyone building the project.

I suppose it is OK. But perhaps the assertion in setup.py could be updated to give a better failure message. Adding a prompt to run:

pip install setuptools --upgrade

would be pretty helpful

The PyGithub Github class does not require credentials to be instantiated, and the search API does not require credentials to search public repositories.

Therefore the config file should be optional, and gisrep init should not be required to be run prior to using the tool.

Tests should be documented like source code - e.g. fixtures can be printed with pytest and docstrings are used to describe them.

Pylint should probably be applied to the tests to enforce this. This likely requires an init.py file in the tests directory.

Setup.py does not specify the template files (.tplt) as part of the package, thus the distributed 0.1.0 version has no templates.

Setup.py must be updated to bundle the template files as module data.