how to create a new narrafirma release.txt

How to Create a New NarraFirma Release

Note: These are my instructions to myself (Cynthia Kurtz) on how to do this. 
They refer to the conditions and locations I am working with.
They might not be exactly the same for you. Still, I have checked
them in to the GitHub repository so as to keep them safe for me
and available for others to learn from (in case they ever work on
NarraFirma in the future).

====================================================================
A. Update version numbers
====================================================================

In Visual Studio Code (VSC), replace the old version number with the new version number. 

Version numbers are in these files:
- package.json
- versions.ts
- wordpress-plugin/narrafirma/narrafirma.php (in two places!)

And (in the list of all versions) in:
- TODO.txt 
- wordpress-plugin/narrafirma/readme.txt

====================================================================
B. Update to-do list
====================================================================

Make sure TODO.txt is up to date with new version number. Make sure to-do items
under new version number match commits made since last version.

====================================================================
C. Update WP readme
====================================================================

Open readme.txt in wordpress-plugin > narrafirma folder and:

C1. Make new version number section in "changelog". Copy section of TODO done
things there (or rewrite more nicely).

C2. Add new section in "Upgrade Notice" section. Say why people should upgrade.

C3. Update the Version number at the top of the file.

C4. Update the "Tested up to" (WordPress version) if needed.

Check in all of these changes (made in A, B, and C) to Github.

====================================================================
D. Remove .DS_Store files
====================================================================

D1. In the Visual Studio Code terminal, type

    find . | grep .DS_Store

You will see a list of all the .DS_Store files.

D2. Type

    find . -name ".DS_Store" -type f -delete

This will delete all of the .DS_Store files. (Then do the first find command
again to make sure they are gone.)

You don't have to do this every time you rebuild the WP plugin, just the LAST
time you build it before the release. If you are still testing you can leave
this step out. But MAKE SURE YOU DO THIS before you build the FINAL distribution
copy of the plugin zip.

====================================================================
E. Build WP version
====================================================================

Open a terminal. CD to the NarraFirma project's top-level directory. Type:

    npm run build-wp

====================================================================
F. Test WP version
====================================================================

Test the WordPress zip file by loading it onto your local WordPress
installation.

F1. Open the Bitnami Wordpress Stack application (icon is a gear with
manager-osx)

F2. In the Bitnami app, click the "Services" tab, then start the Apache Web
Server, MySQL, and PHP-FPM. 

F3. In the Bitnami app, click the "General" tab, then click "Go to Application." 
The browser should take you to the WordPress site. 

(You may need to temporarily turn off the node.js server if you are running it 
on the same port. Or you can change the WordPress port. 
It is set in the Bitnami Wordpress Stack application, 
under the "Network" tab. To change it, in the "Network" tab,
select the "localhost" server, then click "Edit.")

F4. Login to WordPress. In the WordPress dashboard,
deactivate and delete the old version of the NarraFirma plugin.

F5. Load the new plugin version
(Workspace/NarraCoachProject/distribution/narrafirma.zip) and test that
it works.

Keep building and testing the plugin until you are sure the new version works
correctly. Remember to remove the .DS_Store files when you are done testing and
are ready to finalize the last zip file for the version.

====================================================================
G. Create GitHub tag
====================================================================

G1. In the VSC terminal, type

    git tag

This will show you all the previous tags. (To get out of the context
in which the tags are shown, type Q.)

G2. Create a git tag, with a command like this:

    git tag vX.X.X

where X.X.X is the release number.

G3. Push the tag up to the server. Type

    git push origin vX.X.X

(If you make a mistake and set the tag before you finish committing your
changes, do:
    git push --delete origin vX.X.X
and
    git tag --delete vX.X.X

then commit your changes, and do steps G2 and G3 again.)

====================================================================
H. Create Github release
====================================================================

H1. Go to the Github site. THIS MUST BE DONE FROM CHROME, NOT FIREFOX. Login. Click on
Releases. Then click "Draft a new release".

H2. Choose the version tag you already pushed from the drop-down list (vX.X.X).
Then give the release the title "NarraFirma vX.X.X"

H3. Describe the version. At the end of the text field, paste this text:
----------------------------------------------------------
**To use the WordPress version of NarraFirma**, first download the zip file
(narrafirma-wordpress-plugin-vX.X.X.zip) from the link you see on this page. Then
upload the zip file into the plugins section of a running WordPress
installation. _Caution! Don't mix up the WordPress zip file
(narrafirma-wordpress-plugin-vX.X.X.zip) with the source code file
(narrafirma.zip)._

For more installation instructions, go to
[https://narrafirma.com/home/setting-up-narrafirma](https://narrafirma.com/home/
setting-up-narrafirma).
----------------------------------------------------------
(replace X.X.X with the new version number!!!! TWICE!!!)
(also, take the carriage returns out of the text after you paste it in)

H4. WHILE THE RELEASE IS STILL A DRAFT, click "Attach binaries by dropping them
here or selecting them". Pick the "narrafirma.zip" file in the distribution
folder. DO NOT RENAME THE ZIP FILE LOCALLY. Upload it.

H5. Rename the file after uploading it, on Github, to
narrafirma-wordpress-plugin-vX.X.X.zip.

H6. Click "Publish release." Check that it looks okay.

====================================================================
I. Update WP SVN repository
====================================================================

I1. In VSC, do File-New Window. If "narrafirma-wp" is not in the Recent section,
click "Open folder" and choose "narrafirma-wp".

(If the "narrafirma-wp" folder doesn't exist, go to the Workspace folder (in the
terminal) and type "svn co http://plugins.svn.wordpress.org/narrafirma/". ("co"
means "checkout") It will not create a folder called "narrafirma-wp" so you need
to rename the folder so it says that. It may destroy any existing folder called
"narrafirma" so if you have one you will need to rename it first so it doesn't
get overwritten.)

I2. Open the terminal view in that VSC window (on narrafirma-wp). Type

    svn status

to make sure the code there is up to date with the WordPress svn repository. If
there is no response to the command, it is up to date.

-----------------------------------
If (and only if) it says there are any changes to the svn repository
(which would only happen if you had not updated the svn database completely/correctly
after the last release/change, and this should rarely happen), 

type

    svn update

If any new files have been added, you must do a

    svn add

for the new file. Any new file added to the project has to be handled
this way. DO NOT LEAVE NEW FILES OUT OF THE RELEASE!!! 
If you see a file and it has a question mark to its left,
it means you need to add that file to the SVN repository.
-----------------------------------

I3. Open three Finder windows. 

WINDOW 1: Navigate to Workspace/NarraCoachProject/distribution. 
Find the file narrafirma.zip there. 
It was generated by the "npm run build-wp" command. 

WINDOW 2: Navigate to NarraFirma/wordpress plugin/release zips. 
If there is an unversioned "narrafirma" folder sitting there 
(left over from a previous release), delete it. 

WINDOW 3: Navigate to Workspace/narrafirma-wp/trunk.

Copy the narrafirma.zip file from the distribution folder (WINDOW 1) 
to the "release zips" folder (WINDOW 2). 
If there is an existing narrafirma.zip file, replace it.
Then unzip the zip file in place. 
(This folder is temporary. You can delete it later.)

I4. Copy the unzipped folder's contents (BUT NOT the "assets" folder) to
Workspace/narrafirma-wp/trunk (WINDOW 3). Choose "Replace" and "Apply to all" 
so all of the files are replaced with new versions.

NOW CLOSE WINDOW 3. You don't need it anymore, 
and it will cause problems later if you leave it open.

I4a. Go back to the VSC terminal (looking at narrafirma-wp) and type:

    svn update

then

    svn status

Modified files should have an M to the left of their names. 

I4b. Check for new files

If any new files have been added, they will have a ? to the left of their names 
instead of an M. If you see any question marks, you MUST enter the command

    svn add <file name>

for each new file. Copy the file name from the "svn status" output 
(the whole thing, starting with "trunk").

Any new file added to the project has to be handled
this way. DO NOT LEAVE NEW FILES OUT OF THE RELEASE!!! 
Any files with a question mark will not be added to the WordPress version of the code, 
and the plugin will falter when that code is accessed. (Never mind how I know that.)

Check that every file has either an "M" or an "A" in front of it. 
No files should have question mark in front of them.

I4c. Check for removed files

If "svn update" shows you files that have been "restored" 
because they exist locally but not on the WordPress SVN repository,
you need to remove them from there. Type

    svn delete <file name>

for each "restored" file.

I5. Still in the terminal view in VSC (looking at narrafirma-wp), remove
all .DS_Store files from the narrafirma-wp folder. Type

    find . -name ".DS_Store" -type f -delete

Make sure you do not have the folder open in Finder while you are doing this,
because it will make new .DS_Store files.

I6. Still in the VSC terminal (looking at narrafirma-wp), type

    svn status

again, to double-check that each file name has an "M" in front of it.

I7. Still in the VSC terminal (looking at narrafirma-wp), type:

    svn cp trunk tags/X.X.X

I8. Still in the VSC terminal (looking at narrafirma-wp), type:

    svn commit --message "Version X.X.X"

It should say:

Transmitting file data....... done
Committing transaction...
Committed revision <number>.

I9. If svn asks for the password, look in the place 
you usually put passwords for "Wordpress.org forums: password".

====================================================================
J. Final check and announcement
====================================================================

J1. Check that the release has shown up on

    https://wordpress.org/plugins/narrafirma/

It will take a few minutes for the uploaded release to show up. Keep checking
until you see it.

J2. Go to narrafirma.com and log in. Check that the update notice for the 
NarraFirma plugin comes out all right and that there are no problems updating it.

J3. Write a release blog post for the NarraFirma web site. Copy the writing from the
GitHub release.