Updating the project template

[akhanf]

Thought it would be good to discuss what we ultimately want the template project to include..
Let me know what you guys think of the items below:

General philosophy:

• I think the project template is a way of prescribing the 'minimum' best practices we think snakebids workflows/apps should have. Ultimately I would like to see this as an "open by design" approach, where we make it easy for users to adopt the best FAIR practices. But we should also be careful to keep the barrier to entry low, and not make it onerous to initiate a snakebids workflow (e.g. limiting how many extra accounts, like readthedocs etc, are needed).

Package management:

• I'd like to use poetry for this, and have a pre-populated pyproject file that includes the project + dev dependencies, along with the console-script entrypoint.
• This would mean poetry would be a requirement, but I think it's ok to be prescriptive here.. At least for our lab I'd like everyone using poetry anyways.
• If this is being to prescriptive, we could consider having other options -- conda?

Deployment of the workflow:

• Deploying to pypi requires additional set-up (account & token), so I am thinking the default deployment option could just be pipx install git+http://.... Could also have dev instructions that just uses poetry.
• Q: does pipx read the poetry lock file? Or would we need to have a requirements.txt exported?
• Might still be useful to make pypi deployment an optional feature of the template

Linting:

• In e.g. hippunfold, we use: snakefmt, black and isort. Any reason not to include any of these? Any others to add? The snakemake --lint is way too restrictive in my experience..

Release drafter:

• I see github now has built-in capability for this, so we probably don't need specific actions for it, especially if the default deployment is with pipx from github

Testing:

• I think having a standard location for dry-run test bids datasets, maybe even including some typical ones in the template, would be useful
• Dry-run test is an easy one that could be included in every workflow
• Snakemake has some unit-testing capability I haven't explored at all, worth having a look perhaps..

Docs for end-users of the workflow:

• Instead of readthedocs (that would require workflow authors to have that set-up) simpler option is just a pre-populated README.md

Docs for the workflow author:

• we should have simple instructions on how to use the template (e.g. step 1 install poetry , step 2 add github token ... ), maybe this goes in snakebids documentation
• I do like the snakebids create functionality, but it is a bit of a convoluted process for a new user -- (e.g. user needs to install snakebids first).. perhaps just recommending users to pipx install snakebids is the way to simplify this?
• By the way, I've just recently noticed that snakemake's project template has moved away from cookiecutter, and they are just using github's "template" feature. It perhaps makes maintaining and using the template much easier, and also maintains linkage from the template to the instantiation. But the templating with cookiecutter is lost, so requires more work for the workflow author to get the template up and running..

[kaitj]

Package management

I agree about the use of Poetry here and don't necessarily think its an issue to have it as a requirement. Can always link to the poetry documentation for recommended installation.

Deployment of the workflow

I'm open to different options here. I do think the easiest is to pipx install git+https://..., but stability of the installed package is a concern and should come with a warning. Take for example snakebids itself, anything we merge in would be on the main branch and could result in introduction of bugs (I think we do a pretty good job of reviewing and testing, but this may not be the case for all packages). I wonder if the release tags can be used here? Ultimately, I think a stable package deployment should probably still be through pypi (maybe a link or instructions on how to set up?).

Linting

I can't think of anything else at the moment. Wondering if it would be beneficial to include pre-commit hooks, though this adds on one more thing to "setup" for development.

Release drafter

Cool - we could also look into making the switch. I saw it being used I think in tar2bids, would be interested in seeing how it works.

Testing

This one I am having a little bit of trouble envisioning. Dry-run testing is the only one I can see being feasible to implement - maybe Snakemakes unit-testing can help with this. Otherwise I see this as more developer dependent on making sure appropriate tests are included

Docs for end-users of the workflow

Agree with this. I think a README should be required - the readthedocs is nice to have but not a necessity.

Docs for the workflow author

I saw the github template option the other day and was wondering if it would be a good option for something like this. Perhaps a combination of the two? A bare-minimum gh template with instructions in the documentation. Would still lose the cookiecutter aspect though.

[tkkuehn]

Package management

I think prescribing poetry is fine and if a user doesn't want to use it, they can edit their generated app accordingly. (That's true of pretty much anything in the template, now that I think about it.

Deployment of the workflow:

I thiiiiink as long as the PEP-517 stuff is included, pipx will use the dependencies specified in pyproject.toml (not poetry.lock) when you install using git+https://..., but this does bear some more testing.

I think as long as poetry is set up, just running poetry publish will handle publishing to PyPI if/when a developer is ready.

Docs for end-users of the workflow:

We can also just have a mostly blank sphinx docs directory, even if we don't handle setting up readthedocs. This could also be enabled/disabled with a flag for snakebids create

Docs for the workflow author:

pipx run snakebids create seems to do the job in one command.

I haven't seen GitHub's template feature before but would be open to trying it. One consideration is that I think it would be good on our end to include tests in the CI that ensure the template is always current and/or functional.