FIXES #1224 - Added contribution section to README.md

[consideRatio]

Fixes #1224 by providing a section in the README.md on how to setup a development environment.

[juhasch]

Thank you for your contribution. This is a good idea and we were actually discussing this here: #1213.

I think it is better adding a new CONTRIBUTING.md and just add a link in the README.md.
This way it is easier to add new content without making the readme unwieldily large.

Can you change the PR to provide a CONTRIBUTING.md ?
You can also take a look at the Wiki entry here:
https://github.com/ipython-contrib/jupyter_contrib_nbextensions/wiki/Create-a-new-Notebook-Extension

[consideRatio]

Thank you for the input @juhasch ! This is now based this on @benelot wiki entry. I added a section on how to setup development and tried to update the text to an audience interested in contributing in some way but not necessarily creating an extension.

---

Contributing to jupyter notebook nbextensions

We are super happy that you intend to contribute to the nbextensions! You can discuss improvements in issues and improvement them in pull requests.

Create an issue

Do not hesitate to open up an issue, you can discuss bugs, improvements or new extensions in them. Creating an issue is a good starting point for code contributions. The community can support you with experience of similar extensions, pros and cons, what to look for etc.

Here is an example issue of how @benelot did it that worked pretty smoothly: #1193

Setup development

1. Fork and clone
   First fork this repo, then clone your fork. In this way you become prepared to make a pull request.

# clone your fork
git clone https://github.com/<your-github-username>/jupyter_contrib_nbextensions.git
cd jupyter_contrib_nbextensions

2. Setup

# run from the main directory, where setup.py is
pip install --editable .
jupyter-contrib-nbextension install --symlink --sys-prefix

Create an extension

Add a folder with the name of your new extension to jupyter_contrib_nbextensions/nbextensions. Check out the Jupyter Notebook extension structure link to know what has to be in that folder and what the general conventions are.

Create a pull request

As you are ready with your code contribution, make a pull-request to the main repo and briefly explain what you have done.

Here is an example pull request of how @benelot did it that worked super well: #1213

Please also update the CHANGELOG.md.

[jcb91]

Looks good to me, thanks @consideRatio for your work on this. There's a comments inline, plus could you add CONTRIBUTING.md to the MANIFEST.in? Thanks again 😄

[jcb91]

Although a good idea where available, --symlink doesn't work properly on Windows.
This could probably benefit from a little explanation.

[jcb91]

This should go in the unreleased/github master section, since 0.4.0 has already been released.

[jcb91]

Also, it's contributING.d (not contributION.md)

[jcb91]

I think this was meant to read 'and implement them in pull requests'?

[consideRatio]

Thank you for the code review @jcb91 !! I'll fix it all!

[consideRatio]

@jcb91 done!

Technical detail: I made a rebase on this repo's updated master branch, and then a force push to my fork, making your code review comments dangle as those commits no longer have the same hash. I can't see how it would affect anything other than that though, but my experience is lacking when it comes to this.

[jcb91]

Thanks @consideRatio, rebase is fine. I've added a couple more clarification notes about virtual environments, and the possibility of using github for small direct edits of things like docs. Looks good to merge, I think

[consideRatio]

Ah nice! This looks good! I did not know about Github edits!

---

Off topic: I was confused by how you have made edits to this PR, and have tried to learn about it by googling and reading.

I'm thinking of questions like:

• Where is this changed PR code stored?
• What would happen if I made additional changes now?

I read the following, but is still confused.

• https://coderwall.com/p/ffacww/editing-incoming-pull-requests
• https://gist.github.com/Chaser324/ce0505fbed06b947d962

[jcb91]

I was confused by how you have made edits to this PR

It was perhaps a little impolite of me to just push, and it might have been nicer/less confusing to make a PR to your fork from mine. For how it works, I've attempted an outline below:

I'm thinking of questions like:

Where is this changed PR code stored?
What would happen if I made additional changes now?

Essentially what's going on here is that I have pushed commits to the readme-pr branch of your github fork consideRatio/jupyter_contrib_nbextensions. There's a small suggestion that this is possible near the bottom of the PR page, just above the status box:

Normally, I would not have permission to push to your fork, but since September 2016, GitHub PRs provide a setting which allows anyone with push access for the repo to which you're making the PR (in this case, I have push access for ipython-contrib/jupyter_contrib_nbextensions) to push to the PR branch on the fork from which the PR comes (in this case, readme-pr on your fork). You can set this when creating a PR:

Or afterwards for PRs you own (opened) - see the tiny checkbox at the bottom of the right-hand side panel:

Also, this help page gives some more info and links.

So, if you were to make further changes to your local branch, you'd end up having diverged from your github repo. To avoid this, you'd need to either pull changes from your github repo before making further edits locally, or else rebase/merge changes already made locally onto/into the newly-updated github branch, before pushing the updated history up to your fork again. Make sense?

[consideRatio]

Wow @jcb91 that made perfect sense, thank you a lot for the effort of explaining this to me, I could get it very very quickly due to this thorough explanation!