wip

Author: simonjayhawkins

windows.md

@@ -1,74 +1,82 @@
+# README for MS Windows Users
 
+## Preparing for Your First Release
 
-install Docker
+Install Docker
 
-ensure the following repositories are forked to your GitHub account
+Ensure the following repositories are forked to your GitHub account
   - https://github.com/pandas-dev/pandas-website
   - https://github.com/conda-forge/pandas-feedstock
   - https://github.com/MacPython/pandas-wheels
   - https://github.com/pandas-dev/pandas   
 
-
 Open an Anaconda Prompt
+<!-- 
 TODO: resolve git bash Docker volume issues so that make can be used on host
+ -->
 
+Build a Docker image with the conda base environment configured and repositories initialized.
 
-build a Docker image with the conda base environment configured and repositories initialized.
-
-change GH_USERNAME to your Github username
+**change GH_USERNAME to your Github username**
 
 ```
 docker build -t pandas-release --build-arg GH_USERNAME=simonjayhawkins -f docker-files/windows/Dockerfile .
 ```
 
-next we will prepare a Docker container for interactive use during the release process and copy the repositories
+## Preparing the Release Environment for a New Release
+
+Next we will prepare a Docker container for interactive use during the release process and copy the repositories
 from the Docker image into a Docker volume for building the distribution and testing.
 
-to start with a clean volume (after a previous release)
+To start with a clean volume. (after a previous release)
 
 ```
 docker volume rm pandas-release
 ```
 
-change TAG to the release version
-
+**change TAG to the release version**
 ```
 docker run -it --env TAG=v1.0.5 --name=pandas-release -v pandas-release:/pandas-release pandas-release /bin/bash
 ```
 
-the Docker release container should be now be running
+The Docker release container should be now be running.
 
-make sure the repos are up-to-date
+Make sure the repos are up-to-date
+<!-- 
 TODO: also make sure conda environment is up-to-date and pandas-release repo is up-to-date if
 re-using an older Docker image
-
+ -->
 ```
 make update-repos
 ```
 
-Tag the release (This doesn't push the tag)
+Tag the release. (This doesn't push the tag)
 
 ```
 make tag
 ```
 
-stop the container
+Stop the container.
 ```
 exit
 ```
 
-create the Docker image for the sdist build, pip test and conda test containers
-TODO: maybe update the image with apt-get for cached build
+## Preparing the Build and Test Environment
+
 
+Create the Docker image for the sdist build, pip test and conda test containers
+<!-- 
+TODO: maybe update the image with apt-get for cached build
+ -->
 ```
 docker build -t pandas-build .
 ```
 
-build the sdist
-
+## Build the sdist
+<!-- 
 TODO: some of the next steps are repetative. set WORKDIR and symlink to /pandas in pandas-build Docker image instead
 TODO: add container name (as in Makefile) and do not destroy container on exit
-
+ -->
 ```
 docker run -it --rm -v pandas-release:/pandas-release pandas-build /bin/bash
 
@@ -81,10 +89,13 @@ cd pandas-release/
 exit
 ```
 
-pip tests
-
+## Pip Tests
+<!-- 
 TODO: avoid need to pass explicit filename below
 TODO: add container name (as in Makefile) and do not destroy container on exit
+ -->
+
+**change filename to the release version**
 
 ```
 docker run -it --rm -v pandas-release:/pandas-release pandas-build /bin/bash
@@ -99,10 +110,12 @@ exit
 
 ```
 
-conda tests
-
+## Conda Tests
+<!-- 
 TODO: add container name (as in Makefile) and do not destroy container on exit
 TODO: avoid need to re-type version below
+ -->
+ **change PANDAS_VERSION to the release version**
 
 ```
 docker run -it --rm --env PANDAS_VERSION=1.0.5 -v pandas-release:/pandas-release pandas-build /bin/bash
@@ -117,35 +130,47 @@ exit
 
 ```
 
-copy the sdist file from the Docker volume to the local host
+## Copy the sdist File from the Docker Volume to the Local Host.
+<!-- 
 TODO: avoid need to enter specific filename below (maybe just copy contents of dist directory instead)
+ -->
+**change filename to the release version**
 
 ```
 docker run -t --rm -v %cd%:/local -v pandas-release:/pandas-release pandas-release /bin/bash -c "cp /pandas-release/pandas/dist/pandas-1.0.5.tar.gz /local/"
 ```
 
-Push the tag. No going back now.
+## Push the Tag. 
 
-restart the release container
+**No going back now.**
 
+Restart the release container.
+<!-- 
+TODO: does this need to be in interactive mode 
+ -->
 ```
 docker start pandas-release -i
 
-...
+make push-tag
+```
+
+## Create New Branch
+(not needed for Patch release)
 
 On pandas you should also now create and tag a new branch, so
 
 ...
-```
+
+## Create a Release
 
 Now manually create a release https://github.com/pandas-dev/pandas/releases
 
 Make sure to upload the sdist as the "binary". Conda-forge uses it.
 
 
-Start the binary builds.
+## Start the Binary Builds.
 
-restart the release container
+Restart the release container.
 
 ```
 docker start pandas-release -i
@@ -162,17 +187,11 @@ Open PRs for each of those.
 Note that `make wheels` actually pushes a job to MacPython to produce wheels which we will download later.
 
 
-Docs. You can cheat and re-tag / rebuild these if needed.
-
-<!-- doc:
-	docker run -it \
-		--name=pandas-docs \
-		-v ${CURDIR}/pandas:/pandas \
-		-v ${CURDIR}/scripts/build-docs.sh:/build-docs.sh \
-		pandas-docs \
-		/build-docs.sh -->
-
+## Build the Docs.
+You can cheat and re-tag / rebuild these if needed.
+<!-- 
 TODO build an intermediate doc image (and why pandas conda env not in Docker image?)
+ -->
 ```
 docker run -it --name=pandas-docs -v pandas-release:/pandas-release pandas-docs /bin/bash
 
@@ -192,7 +211,7 @@ conda env create --file=/pandas/environment.yml --name=pandas
 exit
 ```
 
-copy the built doc files to host and manually inspect html and pdf docs.
+Copy the built doc files to host and manually inspect html and pdf docs.
 
 ```
 docker run -it --rm -v %cd%:/local -v pandas-release:/pandas-release pandas-release /bin/bash -c "cp -r /pandas-release/pandas/doc/build/ /local/pandas-docs"