`doit` gallery

[vlcinsky]

The idea: users inspired by examples of doit usage

Link to experimental gallery: https://github.com/pydoit/doit-gallery/issues

doit users may inspire each other by sharing their use of doit. Even plain output of $ doit list or $doit list --all may reveal to others unexpected but valuable way of using doit.

Proposed content

Purpose annotation

Short summary of intended use and purpose of given doit application. It shall be very short. It might be handy to use user story format as:

As a user of my personal notebook I want to be able setting notebook connectivity (wifi, mobile internet) up and down from command line as command line is my most favourite UI.

Short or long list of doit tasks

Apart from title, which would described the purpose of given doit usage, users would provide output of doit list and doit list --all.

$ doit list
available   List all available configured connections.
status      List currently active network connections.
up          Set given connection up (specific connection name required).
down        Set given connection down.
radio       Report status of network radio devices
radioon     Set network radio device on
radiooff    Set network radio device off.

To make it more educative and to allow hiding sensitive information from it, it would be allowed to edit the order of commands and to modify (slightly) the text shown.

The same applies to $ doit list --all if it adds any value:

available       List all available configured connections.
status          List currently active network connections.
up              Set given connection up (specific connection name required).
up:VPN
up:home
up:office
up:hotspot
up:train
up:mobile
down            Set given connection down.
down:VPN
down:home
down:office
down:hotspot
down:train
down:mobile
radio           Report status of network radio devices
radioon         Set network radio device on
radioon:wifi
radioon:wwan
radiooff        Set network radio device off.
radiooff:wifi
radiooff:wwan

Example of real usage

Describe more details about usage. Whatever gives the reader better idea about it. No need to be exhaustive, it shall just inspire, not instruct how to do it.

E.g.:

When I travel by train and want to connect to (already preconfigured) train wifi:

$ doit up:train
.  up:train
Connection succesfully activated (Active D-Bus path: /org/freedesktop/NetworkManager/ActiveConnection/1)

When in aeroplane, before take-off I switch all radio network devices:

$ doit radiooff
.  radiooff:wifi
.  radiooff:wwan

When on the road and in need of mobile connectivity provided by LTE modem within my notebook:

$ doit up:tm
.  up:mobile
Connection succesfully activated (Active D-Bus path: /org/freedesktop/NetworkManager/ActiveConnection/3)

doit added value

What are the main advantages of using given doit based solution.

E.g.: Set of nmcli calls (e.g. $ nmcli c up mobile) packed into well named doit tasks, which are easy to call and easy to list when one needs to remind how they are named.

Meta (versions etc.)

Provide information about environment, where it is used, e.g.:

• Python: 3.6
• doit: 0.30.3
• OS: Ubuntu 16.04

Users

Describe the type of users, their number etc.

• Number of users: 1
• Type of user: developer living on command line

commands and packages used

Just list what command line tools are expected to be installed and what python packages installed.

shell commands

• nmcli (network manager CLI)

python packages

• doit

dodo file

Did you use dodo.py, used another file name and pointed to it via command line switch or this stuff is embedded into another application?

Is dodo file standalone, imports other python packages of your own or other python packages

dodo file dependencies:

• standalone dodo file
• import tasks or actions from other modules within the same project
• import tasks or actions from other packages installed

Possibly describe size of the file (number of lines of dodo.py)

Is the code available somewhere? (either url or "no", do not promise publishing as it generates noise as others would ask you to share it really)

e.g. single dodo file dodo.py, 82 lines. Not shared.

doit technologies used

Insight into what doit features were used. No need to show off the author knows a lot and uses a lot, in fact, one can show off, things can be done real simple.

• file dependency (file_dep): yes/no
• task dependency (task_dep): yes/no
• clean task (clean): no/yes/custom
• python-action: yes/no
• cmd-action: yes/no
• calculated uptodate (uptodate): yes/no
• subtasks: yes/no

Any other interesting stuff

Provide any more details, which might be interesting.

Collecting and publishing gallery items

Gallery shall not generate too much extra burden and obligations. Expectations are:

• for contributor (of gallery item):
  • easy to add and edit
• for gallery maintainer:
  • do not generate any extra burden, if not necessary
• for gallery visitor:
  • simple to find and read gallery entries.

I was considering following options:

• a blog
• github source repository
• github wiki page
• github issue tracker
• Google Spreadsheet (a form to commit the entry)

In fact, there are two roles: to collect and to publish. In some cases they can be merged.

To me the optimal solution seems github issue tracker in dedicated repository.

Dedicated Github repository doit-gallery

Here I detail my proposal for using Github repo:

Set up Github repository pydoit/doit-gallery.

Create README.rst there, explaining code of conduct:

• purpose of this repository
  • allow sharing information about different doit usage
    • contributors file issues describing their case
    • readers read about them
  • nothing more: no code, no issue resolution
• for contributors
  • just file an issue describing your usage. Use the template.
• for maintainers:
  • if feasible, add tags allowing to sort issues/items
• for readers:
  • search issues, learn a bit about different users
  • this is not the place to ask for support
• issue edits/conversation
  • keep the noise to minimum. The purpose is to share, not to discuss
  • Consider the initial issue text as the article. Edit it, if necessary. Additional comments (following the initial issue entry) shall serve just to clarify content of the initial issue entry.

Roadmap

• Agree on the gallery concept and initial approach
• Set up github repo pydoit/doit-gallery
• Seed with first set of items
• Add README.rst
• Review the approach, fix the code of conduct if needed
• Invite others to contribute

[vlcinsky]

Gallery repo created: https://github.com/pydoit/doit-gallery

Filed first two issues.

[Kwpolska]

Issues look like a bad place for this. Perhaps a wiki? Even better, a wiki on this repository instead of a new one?

[vlcinsky]

@Kwpolska you are right, issues have many disadvantages:

• people are used to use issues differently
• easy to modify without tracking history of changes
• discussion can easily go wild

But issues have advantages too:

• very easy to add and edit
• allows tagging, searching, the index is created automatically

I am in search of a solution, allowing users to share their way of using doit as simply as possible. Plus if it does not generate too much burden for maintenance, then it is good.

With issues everyone knows, how to add a new one, we (already) have there a template to follow.

Regarding wiki, I have mixed feeling about it:

• people are not using it so much (everyone using code repo, some issue tracker, few are using wiki)
• many wikis have obsolete content. I personally do not like reading wikis, it is difficult to find proper page there and often the page is outdated.
• I do not like writing wiki pages as there are too many open questions:
  • how to name the page. Should it be "crypted" camel case name, free text or something else?
  • which syntax is actually to be used?
  • should I care about modifying some index page by adding a link to the created page?
• how to search the pages?

Experimenting with gallery via issue tracker

My plan is to create few entries and see, how it works with issues.

I already learned small lessons:

• default task(s) is important feature of dodo file
• checkboxes are easy to change without editing the issue itself
• no idea, if we can track history of issue modifications

Experimenting with gallery via wiki

If you are more familiar with using wiki, I would propose you to try creating few pages with gallery entries in it. Best in the doit-gallery repository (this may be changed after we complete experiments). You may find out a style, which will work better then issues and good solutions are always welcome.

[vlcinsky]

@Kwpolska btw I thing the proper issue tracker for the gallery is here (continuing with this ticket).