Add a CONTRIBUTING.md to nx-guides

networkx / nx-guides

Examples and Jupyter Notebooks about NetworkX

https://networkx.org/nx-guides/

Creative Commons Zero v1.0 Universal

185 stars 105 forks source link

Add a CONTRIBUTING.md to nx-guides #53

Closed MridulS closed 8 months ago

MridulS commented 2 years ago

Mirror it with what we do in networkx/networkx

MridulS commented 2 years ago

Should we also add an explicit "Authors field" in the notebooks ? Can this be done via the sphinx theme?

rossbar commented 2 years ago

Should we also add an explicit "Authors field" in the notebooks ? Can this be done via the sphinx theme?

This can be done, but may introduce an extra layer of unnecessary complexity... I think the number and degree of contribution is more than adequately reflected in the git history, and it'd be very easy for an "author" field to fall out of sync with the actual contribution history for any given tutorial.

In all, I'm +1 for a nx-style contributors.md doc, and -1 on a per-file "authors" tracker.

inomag commented 2 years ago

Hey @MridulS , I would like to do this. Should I create a PR?

rossbar commented 2 years ago

I know I said I was +1 in my previous comment, but honestly even that feels like overkill. GitHub already has a really nice interface for this info, so it seems silly to duplicate it. Maybe we can just link to the GitHub contribution page for nx-guides from the main page? Doing what NetworkX does (i.e. maintaining a contributor's list manually) seems not worth the effort here.

MridulS commented 2 years ago

Ah wait, I think I meant CONTRIBUTING.md like https://github.com/networkx/networkx/blob/main/CONTRIBUTING.rst 😅

Currently there is no information about how to submit the myst notebooks to the this repo.

inomag commented 2 years ago

Got it. Thanks @MridulS

inomag commented 2 years ago

@MridulS I am thinking of creating another CONTRIBUTING.md for this repository. But I have some queries -

Is the project only meant to be run on Ubuntu & MacOS platforms? Symlink is being used which doesn't work on Windows. Do we need to make some changes there for this project to work on Windows?
Earlier, after creating a pull request, I faced some issues in the CI workflows. Instead of repeatedly making changes in the code and waiting for the workflows to pass, should I include a guide on the workflows so the users can easily check the build process on their local systems?

Apart from that I will include the steps to change from jupyter notebook to markdown using jupytext, maintaining the correct file structure, etc

rossbar commented 2 years ago

@inomag you're right that we definitely need a contributor guide... it probably makes sense for one of us to take the first crack at it since we should (at least in principle) remember how we had structured the project :). I'll try to prioritize this and will definitely ping you to test drive the guide and ask you for feedback!

inomag commented 2 years ago

@rossbar That would be great! I have done some part of it. https://gist.github.com/inomag/e3970148db2b8d07d4caf7a1231890c6

Though it is incomplete, can you give me suggestions what can I include further?