├── .gitignore ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md └── pull-request └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | *.a 9 | 10 | # Distribution / packaging 11 | .Python 12 | env/ 13 | build/ 14 | develop-eggs/ 15 | dist/ 16 | downloads/ 17 | eggs/ 18 | .eggs/ 19 | lib/ 20 | lib64/ 21 | parts/ 22 | sdist/ 23 | var/ 24 | wheels/ 25 | *.egg-info/ 26 | .installed.cfg 27 | *.egg 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .coverage 43 | .coverage.* 44 | .cache 45 | nosetests.xml 46 | coverage.xml 47 | *,cover 48 | .hypothesis/ 49 | 50 | # Translations 51 | *.mo 52 | *.pot 53 | 54 | # Django stuff: 55 | *.log 56 | local_settings.py 57 | 58 | # Flask stuff: 59 | instance/ 60 | .webassets-cache 61 | 62 | # Scrapy stuff: 63 | .scrapy 64 | 65 | # Sphinx documentation 66 | docs/_build/ 67 | 68 | # PyBuilder 69 | target/ 70 | 71 | # Jupyter Notebook 72 | .ipynb_checkpoints 73 | 74 | # pyenv 75 | .python-version 76 | 77 | # celery beat schedule file 78 | celerybeat-schedule 79 | 80 | # SageMath parsed files 81 | *.sage.py 82 | 83 | # dotenv 84 | .env 85 | 86 | # virtualenv 87 | .venv 88 | venv/ 89 | ENV/ 90 | 91 | # Spyder project settings 92 | .spyderproject 93 | 94 | # Rope project settings 95 | .ropeproject 96 | 97 | # mkdocs documentation 98 | /site 99 | 100 | # Auxiliary files associated with emacs 101 | *# 102 | *~ 103 | *.# 104 | .#* 105 | 106 | # Auxilliary files associated with vim 107 | *.swp 108 | VIRTUAL/ 109 | 110 | # Miscellaneous files 111 | .idea/ 112 | Untitled* 113 | untitled* 114 | *debuglog* 115 | .DS_Store 116 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | The code of conduct for this repository is the 4 | [PlasmaPy code of conduct](https://github.com/PlasmaPy/PlasmaPy/blob/master/CODE_OF_CONDUCT.md). 5 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing Guidelines 2 | 3 | Please see [Contributing to PlasmaPy](http://docs.plasmapy.org/en/latest/CONTRIBUTING.html) 4 | for guidelines on how to contribute. 5 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Licenses 2 | 3 | Source code files and code snippets included in this project are 4 | licensed under a [BSD 3-clause license with a patent 5 | grant](#bsd-3-clause-license-with-patent-grant). All other content in 6 | this project, including content produced directly from unmodified 7 | source code and code snippets, is licensed under a [Creative Commons 8 | Attribution 4.0 International (CC BY 4.0) 9 | license](https://creativecommons.org/licenses/by/4.0/). 10 | 11 | Copyright (c) 2017-2018, PlasmaPy Developers. 12 | 13 | ## BSD 3-clause license with patent grant 14 | 15 | Redistribution and use in source and binary forms, with or without 16 | modification, are permitted provided that the following conditions are 17 | met: 18 | 19 | * Redistributions of source code must retain the above copyright 20 | notice, this list of conditions and the following disclaimer. 21 | 22 | * Redistributions in binary form must reproduce the above copyright 23 | notice, this list of conditions and the following disclaimer in the 24 | documentation and/or other materials provided with the distribution. 25 | 26 | * Neither the name of PlasmaPy nor the names of its contributors may 27 | be used to endorse or promote products derived from this software 28 | without specific prior written permission. 29 | 30 | Subject to the terms and conditions of this license, each copyright 31 | holder and contributor hereby grants to those receiving rights under 32 | this license a perpetual, worldwide, non-exclusive, no-charge, 33 | royalty-free, irrevocable (except for failure to satisfy the 34 | conditions of this license) patent license to make, have made, use, 35 | offer to sell, sell, import, and otherwise transfer this software, 36 | where such license applies only to those patent claims, already 37 | acquired or hereafter acquired, licensable by such copyright holder or 38 | contributor that are necessarily infringed by: 39 | 40 | (a) their Contribution(s) (the licensed copyrights of copyright 41 | holders and non-copyrightable additions of contributors, in source or 42 | binary form) alone; or 43 | 44 | (b) combination of their Contribution(s) with the work of authorship 45 | to which such Contribution(s) was added by such copyright holder or 46 | contributor, if, at the time the Contribution is added, such addition 47 | causes such combination to be necessarily infringed. The patent 48 | license shall not apply to any other combinations which include the 49 | Contribution. 50 | 51 | Except as expressly stated above, no rights or licenses from any 52 | copyright holder or contributor is granted under this license, whether 53 | expressly, by implication, estoppel or otherwise. 54 | 55 | ### Disclaimer 56 | 57 | This software is provided by the copyright holders and contributors 58 | "as is" and any express or implied warranties, including, but not 59 | limited to, the implied warranties of merchantability and fitness for 60 | a particular purpose are disclaimed. In no event shall the copyright 61 | holder or contributors be liable for any direct, indirect, incidental, 62 | special, exemplary, or consequential damages (including, but not 63 | limited to, procurement of substitute goods or services; loss of use, 64 | data, or profits; or business interruption) however caused and on any 65 | theory of liability, whether in contract, strict liability, or tort 66 | (including negligence or otherwise) arising in any way out of the use 67 | of this software, even if advised of the possibility of such damage. 68 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # PlasmaPy Tutorials 2 | 3 | [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) 4 | [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](./LICENSE.md) 5 | 6 | 7 | Tutorials on how to use and develop PlasmaPy and on using Python in plasma physics 8 | -------------------------------------------------------------------------------- /pull-request/README.md: -------------------------------------------------------------------------------- 1 | # Creating a Pull Request 2 | This tutorial will walk you through how to request that someone else pulls your changes to their code into their project. 3 | This is called a **pull request**, usually abbreviated to PR. 4 | It is assumed that you are comfortable with using the fundamental git commands (`git add`, `git commit`, etc.) at a command prompt, and that you are familiar with pushing and pulling repositories to and from GitHub. 5 | If you are completely new to git, you may want to first find and go through a tutorial to learn these fundamental commands before continuing with this one. 6 | https://try.github.io/ and https://git-scm.com/book/en/v1/Git-Basics are two such tutorials, but there are plenty of others out there. 7 | 8 | These are the steps necessary to make a PR, each of which will be described in more detail below: 9 | - Fork a repository 10 | - Clone your fork of the repo 11 | - Create a new branch in your local repo 12 | - Make some changes to your local branch 13 | - Push the changes to your fork 14 | - Create PR 15 | 16 | ## Fork a repo 17 | Find and click the '**Fork**' button in the top-right of a GitHub repo that belongs to someone else - e.g.: https://github.com/PlasmaPy/PlasmaPy-Tutorials. 18 | This will make a copy of that repo, and that copy belongs to you. 19 | 20 | ## Clone your fork of the repo 21 | On your fork of the repo (<_your-github-username_>/PlasmaPy-Tutorials), use the '**Clone or Download**' button to download the repo. 22 | Alternatively you can do this manually at the command line with the syntax `git clone https://github.com/<_your-github-username_>/<_name-of-repo_>.git` or `git clone /<_name-of-repo_>.git`. 23 | This is the same as you've done before with any of your other repos. 24 | 25 | #### Remotes 26 | If you run the command `git remote -v` in your newly-cloned repo, you should see that you have one remote called **'origin'**. 27 | Again, this is the same as when you've pushed and pulled a repo to and from your GitHub account before. 28 | 29 | When your repo is a fork of someone else's, it's often useful to deal with that version as well as your own, in which case you may need to add it as another remote. 30 | By convention, that remote is called **'upstream'**. 31 | To do this, you can run `git remote add upstream <_url-of-remote-repo_>`. 32 | In this case the URL for the upstream remote would be https://github.com/PlasmaPy/PlasmaPy-Tutorials. 33 | 34 | ## Create a new branch in your local repo 35 | This step is not strictly necessary to make a PR, but is highly recommended as part of the git workflow in general, so we shall take the time to go through it here. 36 | You can do this with the command `git branch new_contributor` and then `git checkout new_contributor`. 37 | These commands are explained below. 38 | 39 | #### Branches 40 | Branches are a vital feature of git that allow different development tasks to be self-contained. 41 | For instance, to add some new major functionality to a project, you will often want to create a separate branch of your repo. 42 | Splitting off in this way allows you to work on the new feature without affecting the original code at all until you are ready to merge them together. 43 | This means you can return to the original version if you need a clean working environment, or make other updates to that code. 44 | You can also have many different branches at once, so several different features can be developed at the same time without interfering with each other. 45 | 46 | #### Working with branches 47 | To see what branches exist locally in your repo, run `git branch`. 48 | At the moment, this should just show 'master', which is the usual main branch and is the one branch created when you make a new repo. 49 | You can also give this command an argument which is the name of a new branch to create. 50 | So in this repo, run `git branch new_contributor` to make a new branch called 'new_contributor'. 51 | This creates a branch but if you run `git branch` again, you will see that you are still working in the master branch. 52 | To switch to your new branch, run `git checkout new_contributor`. 53 | Similarly, from there you can return to your original branch with `git checkout master`. 54 | 55 | ## Make some changes to your local branch 56 | Make some changes to some document on your local branch of the repo. 57 | For this example, add your name and GitHub username to the contributors list at the bottom of this file (pull-request/README.md). 58 | Commit your changes with `git add` and `git commit`. 59 | 60 | Once you've done this you can see the separation of branches by checking out your master branch again and inspecting it. 61 | If you look at the commit history (`git log`) and open the file again, you will see that the commit you just made and the corresponding changes are no longer there. 62 | Returning to the new_contributor branch restores the commit and the changes. 63 | Don't forget to do this before moving on with the tutorial. 64 | 65 | ### Update your local branch 66 | This is also not strictly necessary but is often a good idea. 67 | 68 | It is important to remember that while we are making changes in our branch of our fork, it is very likely that the main project branch (`upstream/master`) is also changing. 69 | If we don't to anything to account for this, it may cause merge conflicts when we make our PR, which will delay our contribution. 70 | It therefore often makes things easier (particularly for the maintainer of the main code project) for you to pull in any changes to upstream and resolve any conflicts with your changes locally. 71 | Doing this means that when you make your PR, the only differences between your branch and the original are the changes you wish to submit, which is as it should be. 72 | You can do this with `git pull upstream master`. 73 | Note that this pulls the master branch of the upstream repo and merges it into _your current local branch_ - don't make the common mistake of thinking this will update your local master branch, unless that is the branch you have checked out when you run the command. 74 | See below for a bit more on this syntax, which is the same as for `git push`. 75 | 76 | ## Push the changes to your fork 77 | This is very similar to pushing you will have done before, but now you need to take branches into account. 78 | 79 | #### `git push` syntax 80 | Up until now you have likely been doing `git push origin master`. 81 | What this actually does is tell git to push your current branch of the local repo (which is master by default) to the 'master' branch of the 'origin' remote. 82 | 83 | In this case we've been working in a different branch, `new_contributor`, so we don't want to push to the master branch. 84 | Instead we should push to the `new_contributor` branch on origin, if it exists. 85 | If not, we should push to it anyway and git will create it for us, so the command is the same either way: `git push origin new_contributor`. 86 | 87 | ## Create PR 88 | On the GitHub page for your fork of the repo, you should see drop-down menu that says '**Branch: master**' and a button next to it saying '**New pull request**'. 89 | Select the `new_contributor` branch from the drop-down menu and then click the button. 90 | You should then get a page telling you what the base fork and branch are (into which you want your code to be merged), and what the fork and branch are (that you're trying to merge). 91 | For this example those should be `PlasmaPy/PlasmaPy-Tutorials master` and `<_your-username_>/PlasmaPy-Tutorials new_contributor`. 92 | This page also lets you give your PR a title and a description, which you should use to make clear to other developers what the purpose of the PR is. 93 | 94 | When you've added these, click the big green '**Create pull request**' button and you're done! 95 | Now I, or another maintainer of the original repo, have the option to accept or refuse the changes you've made to the code. 96 | 97 | ## Reviewing pull requests 98 | 99 | GitHub allows users to review pull requests that others have 100 | submitted. To begin reviewing code, select the '**pull request**' tab 101 | in the upstream repository followed by the specific pull request that 102 | you wish to review. Select the '**Files changed**' tab to show what 103 | changes the pull request would make. You may then select any changed 104 | line to add a single comment or start a review with multiple comments. 105 | You can also request changes or show your approval for the proposed 106 | changes. 107 | 108 | When reviewing code, it is vital to provide constructive and helpful 109 | comments so that code review can become a positive experience for 110 | everyone. Eric Rose's presentation at PyCon 2017 provides several 111 | suggestions for [constructive code 112 | review](https://www.youtube.com/watch?v=iNG1a--SIlk). 113 | 114 | ## Contributors 115 | 116 | - Drew Leonard (SolarDrew) 117 | - Felipe Nathan de Oliveira (felipenathan) 118 | - Nick Murphy (namurphy) 119 | - Bill Meyer (mfescience) 120 | - Tulasi Parashar (tulasinandan) 121 | - Lucas Morton (lamorton) 122 | - Amit Manchanda (amitmanchanda1995) 123 | --------------------------------------------------------------------------------