rewrite contribution guidelines

Author: jeffjennings

src/contributing/index.md

@@ -5,22 +5,6 @@ slug: '/contributing/'
 
 We are always interested in incorporating new tutorials into Learn Astropy and the Astropy Tutorials series. We welcome tutorials covering astro-relevant topics; they do not need to use the Astropy package in order to be hosted or indexed here. If you have astronomy tutorials that you would like to contribute, or if you have a separate tutorial series that you would like indexed by the Learn Astropy website, see below.
 
-## Overview
-
-Each tutorial is a [Jupyter notebook](https://jupyter.org/) file in a unique repository `tutorial--*` in the [astropy-learn organization](https://github.com/astropy-learn). For example, let's look at the [FITS-header](https://github.com/astropy-learn/tutorial--FITS-header/tree/main/) tutorial. The repository has a few files that authors should always write/amend when contributing a new tutorial or set of tutorials:
-
-- A single Jupyter notebook file that contains the text and code for the tutorial (it should follow the content guidelines below),
-- Any small data files used in the tutorial (in this case, a single FITS file),
-- A `requirements.txt` file that specifies the required packages to run the notebook, and
-- An `AUTHORS.md` file that lists the notebook authors.
-- If you are contributing multiple, thematically-linked notebooks, the `index.md` file should summarize the contents of the individual notebooks (it will be the first page in the 'jupyter book' containing all individual notebooks). Additionally each `.ipynb` filename should be preceded by a number and an underscore, in the order the notebooks should appear in the book, e.g.:
-  ```
-  1_intro-to-modeling
-  2_applying-model-to-data
-  ```
-
-The notebook file(s) are automatically run and converted into a static HTML page ([for example](https://learn.astropy.org/tutorials/FITS-header.html)), which is then displayed in the listing on the main tutorials webpage, http://tutorials.astropy.org.
-
 ## Content Guidelines
 
 ### Overview
@@ -30,9 +14,9 @@ The notebook file(s) are automatically run and converted into a static HTML page
   - _Input/Output_: read in some data (use [astroquery](https://astroquery.readthedocs.io/en/latest/) where possible to query real astronomical datasets)
   - _Analysis_: do something insightful / useful with the data
   - _Visualization_: make a pretty figure (use [astropy.visualization](http://docs.astropy.org/en/stable/visualization/) where possible)
-- The tutorials must be compatible with the versions supported by the last major release of the Astropy core package (i.e. Python >= 3.5)
+- The tutorials must be compatible with the versions supported by the latest major release of the Astropy core package
 
-### Template intro
+### Introduction cell template
 
 The first cell in every tutorial notebook is a markdown cell used for the title, author list, keywords, and summary. All of this information should be contained in a single cell and should adhere to the following format:
 
@@ -47,7 +31,7 @@ Jane Smith (@GITHUB-ID, ORCID-ID), Jose Jones (@GITHUB-ID, ORCID-ID)
 * Calculate ...
 * Display ...
 
-## Keywords (please draw from [this list](https://github.com/astropy-learn/astropy-tutorials/blob/main/resources/keywords.md))
+## Keywords
 Example, example, example
 
 ## Companion Content
@@ -58,6 +42,8 @@ In this tutorial, we will download a data file, do something to it, and then
 visualize it.
 ```
 
+Please draw keywords from [this list](https://github.com/astropy-learn/astropy-tutorials/blob/main/resources/keywords.md).
+
 ### Code
 
 - Demonstrate good commenting practice
@@ -67,7 +53,7 @@ visualize it.
   - Variable names should be descriptive, e.g., `galaxy_mass`, `u_mag`
 - Use the print function explicitly to display information about variables
 - As much as possible, comply with [PEP8](https://www.python.org/dev/peps/pep-0008/).
-- As much as possible, comply with Jupyter notebook style guides - [STScI style guide](https://github.com/spacetelescope/style-guides/blob/master/guides/jupyter-notebooks.md) and [Official Coding Style](https://jupyter.readthedocs.io/en/latest/development_guide/coding_style.html).
+- As much as possible, comply with Jupyter notebook style guides - [STScI style guide](https://github.com/spacetelescope/style-guides/blob/master/guides/jupyter-notebooks.md) and [Official Coding Style](https://docs.jupyter.org/en/stable/contributing/ipython-dev-guide/coding_style.html).
 - Imports
   - Do not use `from package import *`; import packages, classes, and functions explicitly
   - Follow recommended package name abbreviations:
@@ -96,52 +82,15 @@ visualize it.
 
 ## Procedure for contributing a notebook or set of notebooks
 
-There are two methods for submitting a tutorial or set of thematically linked tutorials.
-
-### Method 1: Provide a link
+To contribute tutorial content, open an issue in the [astropy-tutorials repository](https://github.com/astropy-learn/astropy-tutorials/issues). When you click 'New issue', select the 'Tutorial submission' option, completing all fields of that form. You have the option to have your tutorial made citable via an upload (by the Astropy Learn maintainers) to Zenodo. If you have any data files needed by the notebook to run, see the 'Data files' section below.
 
-- [Open an issue on the astropy-tutorials Github repo](https://github.com/astropy-learn/astropy-tutorials/issues) with a link to your Jupyter notebook(s).
-
-Learn Astropy maintainers will download your notebook, test it, and edit the file if necessary to conform to the above style guide. When the tutorial is ready to be incorporated, maintainers will open a pull request on behalf of the tutorial authors.
-
-### Method 2: Submit a pull request
-
-This process for contributing a tutorial involves the [GitHub fork](https://help.github.com/articles/working-with-forks/) and `git` workflow concepts [branch, push, pull request](https://help.github.com/articles/proposing-changes-to-your-work-with-pull-requests/).
-
-To contribute a new tutorial, first fork the [Astropy Learn tutorial template repository](https://github.com/astropy-learn/tutorial--template). Then clone your fork locally to your machine (replace `<GITHUB USERNAME>` with your GitHub username):
-
-```
-git clone git@github.com:<GITHUB USERNAME>/astropy-tutorials.git
-```
+Maintainers will review your notebook and may ask questions and/or suggest edits (e.g., to conform to the above content guidelines). When the review is complete and the tutorial is ready to be incorporated, maintainers will create a new repository for the tutorial, add the notebook(s), and upload your tutorial(s) to the [learn website](https://learn.astropy.org/tutorials/).
 
-Next, create a branch in your local repository with the name of the tutorial you'd like to contribute. Say we're adding a tutorial to demonstrate spectral line fitting -- we might call it "Spectral-Line-Fitting":
-
-```
-git checkout -b Spectral-Line-Fitting
-```
-
-Include the notebook `.ipynb` file(s) and any data files used by the notebook (see the 'Data files' section below). Update the `AUTHORS.md` file. Update the `requirements.txt` file with the Python packages the tutorial depends on and files. For example, if your tutorial requires `scipy` version 1.0 and `numpy` version 1.13 or greater, your `requirements.txt` file would look like:
-
-```
-scipy==1.0
-numpy>=1.13
-```
-
-Push the notebook and other files from your local branch up to your fork of the repository on GitHub (by default, named 'origin'):
-
-```
-git push origin Spectral-Line-Fitting
-```
-
-When the tutorial is ready for submission, [open a pull request](https://help.github.com/articles/creating-a-pull-request/) against the main [`tutorial--template` repository](https://github.com/astropy-learn/tutorial--template), and your submission will be reviewed.
-
-## Data files
+### Data files
 
 If your tutorial includes large data files (where large means >~ 1 MB), including them in the tutorial's repository would drastically slow down cloning of the repository. Instead, for files < 10 MB, we encourage use of the `astropy.utils.download_files` function, and we will host data files on the http://data.astropy.org server (or you can do this directly by opening a PR at the https://github.com/astropy/astropy-data repository). Alternatively, if the file size is > 10 MB, the data should be hosted on Zenodo. To do the former, use the following procedure:
 
-- If contributing your notebook(s) via a pull request, include the data files (e.g., `tutorials/notebooks/My-tutorial-name/mydatafile.fits`). **IMPORTANT**: when you add or modify data files, make sure the only thing in that commit involves the data files. That is, do _not_ edit your notebook and add/change data files in the same commit. This will make it easier to remove the data files when your tutorial is merged.
-
-- To access your data files in the notebook, do something like this at the top of the notebook:
+- Assuming you have a data file named `mydatafile.fits`, you can access the file in the notebook with something like this at the top of the notebook:
 
   ```
   from astropy.utils.data import download_file
@@ -160,7 +109,7 @@ If your tutorial includes large data files (where large means >~ 1 MB), includin
       ...
   ```
 
-  If you do this, the only change necessary when merging your notebook will be to set `tutorialpath` to `'http://data.astropy.org/tutorials/My-tutorial-name/'`.
+  If you do this, the only change necessary in your submission of the notebook to [astropy-tutorials](https://github.com/astropy-learn/astropy-tutorials/issues) will be to set `tutorialpath` to `'http://data.astropy.org/tutorials/My-tutorial-name/'`.
 
 For data files that are larger than 10 MB in size, we recommend hosting with Zenodo. To use this approach, follow these steps: