fastai / nbdev

Create delightful software with Jupyter Notebooks
https://nbdev.fast.ai/
Apache License 2.0
4.89k stars 488 forks source link

Add a CONTRIBUTING.md to `nbdev_new` output #1224

Open hugetim opened 1 year ago

hugetim commented 1 year ago

It may be helpful for open-source projects adopting nbdev to have default CONTRIBUTING guidelines to work from, something like the following (derived from https://github.com/fastai/fastcore/blob/master/CONTRIBUTING.md, https://github.com/fastai/fastai/blob/master/README.md, and https://github.com/fastai/fastai/blob/master/CONTRIBUTING.md), with appropriate substitutions made for nbs_path and any other such references.


How to contribute

This project is developed using nbdev, a way to create delightful software with Jupyter notebooks. The Python library and docs are automatically created from the notebooks in the /nbs directory.

How to get started

Before anything else, please install the git hooks that run automatic scripts during each commit and merge to strip the notebooks of superfluous metadata (and avoid merge conflicts). After cloning the repository, run this command inside it: nbdev_install_hooks

How to submit notebook PRs

After making changes to the /nbs notebooks, you should run nbdev_prepare and make any necessary changes in order to pass all the tests.

(You may also make limited changes directly to the .py files in the library, in which case you should sync those changes back to the notebooks with nbdev_update.)

Do you want to contribute to the documentation?

pranith7 commented 1 year ago

@hugetim i want to work on this

hugetim commented 1 year ago

i want to work on this

I don't have plans to work on it myself, so that would be great! Thanks in advance.

pranith7 commented 1 year ago

@hugetim correct me if i am wrong there is already a contributing.md file exists for fastai/nbdev do you want to add it for fastai/nbdev/nbdev

hugetim commented 1 year ago

Well, kind of. I want the nbdev_new command to generate one for you as part of the project files it creates for a new repo. Basically, I want to add it for fastai/nbdev_template.

hugetim commented 1 year ago

One thing that should be added to my template above: an instruction to install nbdev. It can link to: https://nbdev.fast.ai/tutorials/tutorial.html#installation

Additionally, we should spell out the steps to take inside the project directory:

  1. Install jupyter notebook
  2. Install nbdev
  3. Install quarto
  4. Install hooks
  5. nbdev_export
  6. pip install -e '.[dev]'
  7. After making changes, run nbdev_prepare

Here's what I'm using for my project: https://github.com/hugetim/nbstata/blob/master/CONTRIBUTING.md

hugetim commented 1 year ago

Seems relevant: #1103 - Deprecate nbdev-template and bring its files & functionality into nbdev

hugetim commented 1 year ago

It may make more sense to do this as a notebook which generates CONTRIBUTING.md.

hugetim commented 1 year ago

Also relevant: https://github.com/fastai/nbdev/issues/1021 - How to guide for developing nbdev