checklib / checklib

Library of markdown checklists for Reproducible Research. Best used as github issue templates

checklib

Welcome to checklib—a library of checklists to aid you in all your software sustainability and reproducibility needs!

What Are These Checklists?

Have you ever found yourself wondering, "Gosh, I know I'm supposed to be doing [fill in the blank], but I haven't the slightest idea where to start." Our checklists are here to help. At their core, they are simply Markdown files containing checklist items we've deemed useful in making sure you're doing the right things in terms of usability, maintainability, extensibility, etc.

How Do I Use Them?

The project consists of a library of markdown checklists and a simple command line tool for incorporating checklists as GitHub issue templates into your own projects.

Currently you need a local copy of the checklist library to use the tool, as well as a local copy of the project you wish to add checklists to.

• The first step is to go ahead and clone checklib so you have local access to the checklists.

  git clone https://github.com/checklib/checklib

  Make sure to pull before using each time to ensure you have an up to date version of the checklists.
• Navigate to the root of your local copy of checklib.
• Run the checklib tool by running bash ./run_checklib.sh. If you don't supply any arguments (or supply the argument --help) the tool will output information explaining how to use the tool.

View available checklists

In the checklib root:

• Get a list of the available checklists divided by subject use the --ls_lists flag: bash ./run_checklib.sh --ls_lists

Add checklists to your project:

In the checklib root:

• Use the --ls_lists flag to decide which checklists you would like to include in your project
• Run the run_checklib script with those checklists as arguments. For example to add the conda-environment.md and set-up-repository.md checklists you would run:

  bash ./run_checklib.sh conda-environment.md set-up-repository.md
  

• When prompted to by the script, supply the path to your project's repository.

Use them on GitHub

Use the command line tool to add checklists as issue templates as described above. The push your repo to GitHub.

Now when users go to create a new issue through the GitHub interface, they'll be presented with a list of templates from which to choose. Once they've selected one, the new issue page pops up with the description populated with your brand new checklist.

Use them on GitLab

Under construction.

Can I Customize Them to Suit My Needs?

Certainly. Once you've copied them into your repository and they're all set up as issue templates, feel free to customize them to your heart's content. If you come up with something that would be useful for the research software engineering community at large, please send it back to us via pull request.

How Do I Get Support?

If ever you need anything, head over to our support page to see how we can help.

This Is Awesome—How Can I Contribute?

We're glad you asked. We're always happy to have new collaborators. For details on our workflow, check out our contributing guidelines.

License

For our licensing information, check out our LICENSE file.

checklib's Issues

Contrast between header level text seems too faint

Is your feature request related to a problem? Please describe.

The jekyll theme doesn't seem to have enough contrast in text size and boldness between header levels.

Describe the solution you'd like

Can we tweek the css or choose another theme?

Create functionality to deploy selected issues

Want to be able to deploy to at least:

• github: see
• gitlab:

DESIRED FUNCTIONALITY:

• Specify checklist to deploy
• Specify repository to deploy it on
• Defaults to getting checklist templates from checklib repo but should be able to override with customised fork of library

Functionality to pull checklists into a repository

Is your feature request related to a problem? Please describe.

Would be great to allow programmatic pulling of checklists directly into a repositories .github/ISSUE_TEMPLATES

Describe the solution you'd like
Need to figure that out

Still in Use?

What is it you need help with?
Hey @annakrystalli, is checklib still in use? I was going to recommend it to a colleague, but didn't know if it was still up-to-date and whatnot.

Hope all's well. Sorry I'm not able to make it out to the RSECon or Collab20 this time around. Hope to see you all again at some point in the future.

Demonstrate language specific checklist variation

Would like to show how checklists tailored to specific languages/domains can add value. So will develop an R version of a few checklists.

Demonstrate the use of customised library

Show how to deploy a customised version of a checklist

Keep checklist metadata, dependencies, parent/child, categories

@annakrystalli 's triple-style RDF idea to tag checklists with language or domain, maybe nest, refer to prequisites...

Enable Travis for website build/deploy

See https://docs.travis-ci.com/user/deployment/pages/

Populate README

Define structure/attributes of a checklist template

Checklist metadata

The first three lines encode metadata about the checklist and should be structured as follows:

• The first line should always be a h1 (#) markdown header containing the title of the checklist.
• This should be followed by an empty line.
• The third line should be a short description of the task laid out by the checklist

eg.

# Set up GitHub Authentication

Set up GitHub authentication through a Personal Access Token

Checklist

This should be followed by the higher level check list
utilising the - [ ] Task feature
eg.

- [ ] Create New personal access token (PAT)
- [ ] Store PAT as Environment Variable

• Create New personal access token (PAT)
• Store PAT as Environment Variable

Guidance

The rest of the template should can contain any valid GitHub flavoured markdown and should provide more detailed guidance, including code examples and links to further materials.

eg

## Guidance

### Create Personal Authorisation Token


Personal access tokens function like ordinary [OAuth access tokens](https://en.wikipedia.org/wiki/OAuth). They can be used instead of a password for Git over HTTPS, or can be used to authenticate to the API over Basic Authentication.

To create a new PAT visit https://github.com/settings/tokens/new?scopes=repo,gist&description=GITHUB_PAT

The above URL prepopulates the PAT specification with:

- A description for the token: `GITHUB_PAT`
- The scope of the authorisation. This defines the access for personal token and defaults to full access to repos and gists. You can ammend this if required. [Read more about OAuth scopes](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/)


Click Generate token.

Then copy the token to your clipboard. For security reasons, after you navigate off the page, you will not be able to see the token again.

### Store PAT as Environment Variable

Store your PAT somewhere where it can be loaded as an system environment variable. For example, on a unix system you can add the following line to your `.bashrc` file:

export GITHUB_PAT="ahhcjkds45768356bdsjndkkjs78Pak"

[More options for storing PATs](https://stackoverflow.com/questions/46645843/where-to-store-the-personal-access-token-from-github)

Link from Checklist into Guidelines

Describe the solution you'd like
It'd be nice for the individual lines in the checklist to be hyperlinked down to the additional guidelines at the bottom of the template.

Describe alternatives you've considered
Apparently the [link text](#anchor-name) syntax doesn't work within issues; perhaps just in Markdown and Wiki pages.

PERL Library called CheckLib already exists

What is it we need to talk about?

It appears that there already exists a PERL library called CheckLib. To avoid confusion and conflict, what do people think of changing our name to chklib?

Definition of Done
What do we need to accomplish to consider this discussion complete? Ex.

• Decide whether sharing a name with a PERL library is ok
• If not decide on a new name

Would be great to get feedback from @checklib/devs folks

Set Up checklib with All the Necessary GitHub Files

• README
• CONTRIBUTING
• LICENSE
• SUPPORT
• Issue Templates
• Wiki
• PR Template

Browse through catalogue of checklists

• first version: github renders markdown 🎉
• suggest using github pages / jekyll
  • with custom collection of checklists

Run update_checklists.py as part of CI deploy

• currently checking _checklists collection into the repository
• update_checklists.py generates the website/_checklists from the main library

Create catalogue of checklists

This is overview useful for us now for development, to help us direct and track our efforts but also acts as good way for users to:

1. get an overview of what's available and what is already listed as desirable (just not completed)
2. propose new checklists to be added

Decide library structure and some initial examples

Cool logo/logotype

☑️ checklib

- [ ] check_lib

• check_lib

GitHub-ify a Checklist

Describe the solution you'd like
Before one of our checklists is added as a GitHub issue template, it needs to have a YAML header prepended to it. We need a script to do that.

Additional context
The YAML header has the following format:

---
name: <Template Name>
about: <Template Description>
title: ''
labels: ''
assignees: ''

---

Our checklists have the following format:

# <Checklist Title>
<Checklist Description>
<Additional checklist details follow on lines three and below.>