From 89ddd0bf424217dd0655f7f6e88b9630a33d70ce Mon Sep 17 00:00:00 2001 From: anjakefala Date: Mon, 9 Nov 2020 20:35:22 -0500 Subject: [PATCH] [dev] reference checklists in PULL_REQUEST_TEMPLATE Closes #737 --- .github/PULL_REQUEST_TEMPLATE.md | 2 ++ CONTRIBUTING.md | 6 ++++-- dev/checklists/add-loader.md | 26 -------------------------- dev/checklists/add-plugin.md | 16 ---------------- docs/api/loaders.rst | 4 ++++ docs/contributing-to-visidata.md | 28 ++++++++++++++++++++++++++++ 6 files changed, 38 insertions(+), 44 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 dev/checklists/add-loader.md delete mode 100644 dev/checklists/add-plugin.md create mode 100644 docs/contributing-to-visidata.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..74063391f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,2 @@ +- [ ] If contributing a core loader, [the loader checklist](https://visidata.org/docs/contributing-to-visidata#loader) was referenced. +- [ ] If registering an external plugin, [the plugin checklist](https://visidata.org/docs/contributing-to-visidata#plugins) was referenced. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89b5b7961..539a99dea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ We also need people to mention VisiData in their forums and communities that rel Don't spam or do a drive-by promotion; these are largely ineffective and will often be received negatively. Endorsements have more weight from people who actively post about other relevant topics; we don't want to become the "VisiData Brigade". -Finally, if you are on "Web 2.social", you can post a [tweet](https://twitter.com/visidata) or a [tutorial]() or a [demo](https://www.youtube.com/watch?v=N1CBDTgGtOU) or a [host a workshop](), or anything else you think might make people interested in exploring the wonderful world of VisiData. +Finally, if you are on "Web 2.social", you can post a [tweet](https://twitter.com/visidata) or a [tutorial]() or a [demo](https://www.youtube.com/watch?v=N1CBDTgGtOU) or [host a workshop](https://www.meetup.com/pt-BR/Journocoders/events/258035880/), or anything else you think might make people interested in exploring the wonderful world of VisiData. ## Support on Patreon @@ -24,7 +24,9 @@ If VisiData saves you time on a regular basis, and especially if VisiData makes ## Start a Project Using VisiData -If you know Python and want to augment it to suit your own workflow, you can create a loader or a plugin. Here are some great examples: +If you know Python and want to augment it to suit your own workflow, you can create a loader or a plugin. In support of this, I have written [a detailed api guide for VisiData](https://www.visidata.org/docs/api/). + +Here are some great examples: - [jsvine's custom visidata plugins](https://github.com/jsvine/visidata-plugins) - [layertwo's pcap loader](https://github.com/saulpw/visidata/blob/develop/visidata/loaders/pcap.py) diff --git a/dev/checklists/add-loader.md b/dev/checklists/add-loader.md deleted file mode 100644 index 8a5162b9f..000000000 --- a/dev/checklists/add-loader.md +++ /dev/null @@ -1,26 +0,0 @@ -# Loader checklist - -## Writing the loader - -1) create an `open_foo` function that returns a new `FooSheet`; -2) write a `reload()` function to load the data into a list of `rows`; -3) specify the `columns` as a list of `Column` objects; -4) define the sheet-specific [commands](add-command.md). -5) set an appropriate `rowtype` string (plural) -6) make a `# rowdef: ` comment describing the structure of a row (e.g. its base class) - -For additional reading, see our detailed guide on [writing loaders for VisiData](https://visidata.org/docs/loaders/). - -## Testing the loader - -7) if the loader's dependencies are not part of Python3 stdlib, note the additional dependencies in the `requirements.txt`; - - include a comment adjacent to the dep with the name of the loader -8) check-in a small sample dataset, in that format, to the `sample_data` folder; -9) add a `load-foo.vd` to the `tests/`; - - `load-foo.vd` should simply open the checked-in sample dataset and a simple interaction if the source includes multiple tables - -## Documenting the loader (to be done once the loader is shippable) - -10) add a section on the loader to the "supported sources" of the manpage. - - include its non-Python3 stdlib dependency requirements (if any) - - provide a short overview of how the loader allows users to engage with the data diff --git a/dev/checklists/add-plugin.md b/dev/checklists/add-plugin.md deleted file mode 100644 index 51c5948f4..000000000 --- a/dev/checklists/add-plugin.md +++ /dev/null @@ -1,16 +0,0 @@ -# Creating an external plugin - -1. Put all of the Python code in a single .py file in your repo - - Ensure that the plugin has a `__version__`. - -2. In the `visidata/plugins/plugins.jsonl` file in the VisiData repo, add a row for each plugin with all necessary informations: - - `url`: link to where the plugin file is hosted. - - specific commit urls are preferred over branches - - `description`: link to where the plugin file is hosted. - - `latest_ver`: the current version of the plugin. - - `latest_release`: the date the current version of the plugin was shipped. - - `maintainer`: your contact information. - - `visidata_ver`: the latest version of visidata this plugin was tested on. - - `pydeps` (optional): Space-separated list of pip-installable python modules required for the plugin. - - `vdplugindeps` (optional): Space-separated list of vd plugin dependencies. - - `sha256`: SHA256 hash of the contents of the plugin .py file for the `latest_release`. A script for obtaining this hash can be found [here](https://raw.githubusercontent.com/saulpw/visidata/develop/dev/vdhash.py). diff --git a/docs/api/loaders.rst b/docs/api/loaders.rst index 5b1388ea7..99b1f9478 100644 --- a/docs/api/loaders.rst +++ b/docs/api/loaders.rst @@ -1,6 +1,10 @@ Loaders ======= +.. note:: + + You are welcome to submit new loaders to core VisiData, or as plugins. Please, see our `checklists for contribution `__. + Creating a new loader for a data source is simple and straigthforward. 1. ``open_filetype`` boilerplate diff --git a/docs/contributing-to-visidata.md b/docs/contributing-to-visidata.md new file mode 100644 index 000000000..8519d5c53 --- /dev/null +++ b/docs/contributing-to-visidata.md @@ -0,0 +1,28 @@ +# Checklists for Contributing to VIsiData + +## [Submitting a Core Loader](#loader) {#loader} +A deeper explanation of all of these steps can be found [in the api documentation](https://www.visidata.org/docs/api/loaders.html). + +- Create an `open_foo` function that returns the new `FooSheet`. +- Set an appropriate `rowtype` string. +- Provide a `# rowdef: ` comment. This describes the structure of a row (e.g. its base class) in a **Sheet**. +- If the loader's dependencies are not part of Python3 stdlib, note the additional dependencies in the `requirements.txt` (include a comment adjacent to the dep with the name of the loader). +- Check in a small sample dataset, in that format, to the `sample_data` folder +- Add a `load-foo.vd` to `tests/`. `load-foo.vd` should simply open the checked-in sample dataset and have a simple interaction if the source includes multiple tables. +- After replaying `vd load-foo.vd`, save the final sheet as `load-foo.tsv`. Save `load-foo.tsv` in `tests/golden/`. +- add a section on the loader to the [formats.jsonl](https://github.com/saulpw/visidata/blob/develop/dev/formats.jsonl). + +## [Submitting an External Plugin](#plugins) {#plugins} + +- Host a single Python file containing all of the plugin's code. +- Ensure the plugin has a `__version__`. +- In the `visidata/plugins/plugins.jsonl` file in the VisiData repo, add a row for each plugin with all of the necessary information: + - `url`: link to where the plugin file is hosted; specific commit urls are preferred over branches. + - `description`: a description of the plugin. + - `latest_ver`: the current version of the plugin. + - `latest_release`: the date the current version of the plugin was shipped. + - `maintainer`: your contact information. + - `visidata_ver`: the latest version of visidata this plugin was tested on. + - `pydeps` (optional): Space-separated list of pip-installable Python modules required for the plugin. + - `vdpugindeps` (optional): Space-separated list of vd plugin dependencies. + - `sha256`: SHA256 hash of the contents of the plugin .py file for the `latest_release`. A script for obtaining this hash can be found [here](https://raw.githubusercontent.com/saulpw/visidata/develop/dev/vdhash.py).