Skip to content

Updating

Overview

This page is dedicated to explaining how to update JPMN, as well as provide basic support for required steps outside of Anki.

Warning

Updating your card will DELETE ANY CHANGES you have made to the templates.

Please make a complete backup of your collection before continuing to update your note.


Updating: Via Python Script

The recommended way to install the note is by using a python script. This will change the note in place, and gives you various options on how the note will be changed. Lastly, it will give you warnings on anything you have to change manually, such as Yomichan Templates.

Why can't I just copy/paste the templates, or just re-install the .apkg file to update the note?

It's not uncommon for updates to contain many changes outside of just the templates alone. For example, required Yomichan settings, add-on config changes, or sometimes even the data within the note fields must be changed. Additionally, the field list is changed somewhat frequently.

Although settings outside of Anki cannot be changed automatically, almost all settings within Anki are automatically updated with the python script. Additionally, the python script will give you plenty of instructions on exactly how to update any Yomichan setting or add-on config change.

Finally, installing the .apkg file when the field list is in any way different will actually create a new version of the note instead of replacing the old note, which may prove to be an even bigger hassle.


Preliminary steps

Ensure that your note is named exactly JP Mining Note. To do this, head over to:

(Main Window) → ToolsManage Note Types.

If your note is named differently, please rename it to JP Mining Note.

Note

You can always change the name back after updating.


Running the Script

The cross platform command line summary is shown below.

A more user friendly set of instructions for Windows users is also available on the second tab, for people who have never used python or git before.

# assuming you are at the root of the repo, i.e. after the following commands:
#  $ git clone https://github.com/Aquafina-water-bottle/jp-mining-note.git
#  $ cd jp-mining-note

# grabs the latest version of the master branch
git pull origin/master

cd tools

# Make sure you have Anki open and Anki-Connect installed!
# Also ensure that your python version is 3.10.6 or higher.
# Note: Linux users may have to use `python3` instead of `python`.
python install.py --update

This section explains how to run the script on Windows if you have never used python or git before.

  1. Install Python version 3.10.6 or above, if you haven't already. I recommend using the latest stable version if you have not downloaded Python before.

    Additionally, make sure the box for "Add Python to PATH" is checked. (This is a common error for people to make. Please pay attention to this step!)

  2. Get the latest version of the repository. The easiest way to do this is by heading to the main repository, click on the green Code dropdown, and then download the zip by the Download Zip button. After that, unzip the directory.

  3. Open command prompt, and cd (change directory) into jp-mining-note/tools. If you don't know how to do that, see this or this.

  4. With your current directory being the tools directory, run the following command:

    python install.py --update
    
    Once you run the command, further instructions should be given to you through the command line interface.


Common Errors

This section will document common errors that occur when running the install.py script.


Anki-Connect is missing actions

Anki-Connect is likely outdated. To fix this, remove and re-download Anki-Connect from the AnkiWeb page.

Note

It seems that the Check for Updates occasionally fails to update the add-on, despite the fact that a newer version of the add-on exists. That is why I recommend re-downloading from the AnkiWeb page instead of using this feature.


FieldVerifierException

anki field window

This class of errors means that the field list was edited at some point after the installation or last update of JPMN. The field list can be accessed by navigating to the following:

(Main window) → BrowseFields....

The install.py is picky about fields and its order, and by default, the script will reject any note type with modifications to the field list.

To fix this, there are a few cases to go through.

The field order has been changed.

If the field order has been changed, and nothing else has been changed, you should be able to preserve your existing field list order by running the installation script with the --ignore-order flag (i.e. python3 install.py --ignore-order).

Alternatively, you can simply re-order the fields back to their original position.

Note

If you use --ignore-order, all new fields will be added to the very end of the field list (i.e. under Comment). Additionally, any fields that were supposed to be repositioned will stay in place. It is up to you to move the fields to the appropriate places.

New field(s) have been created.

You have two options. Neither of these will delete your existing field(s).

  1. If you want to preserve your existing field list order, then you can run the script with the --ignore-order flag, like above.

  2. If you want to have the field list order match exactly with the current note, then re-order all the new fields to be below the last Comment field. Of course, this can be a temporary move; you can move the fields back to their previous positions after the update.

    Note

    On rare occasions, you might have added a field that serves the same purpose as a field that will be created on update. If so, rename your field to the field that will be added, and move the field under the Comment field.

    For example, if your note doesn't have PAPositions but you added a field Positions that fulfills the same purpose, then rename Positions to PAPositions.

Field(s) were removed or renamed.

Unfortunately, there is no way to ignore removed or renamed fields. If you removed a field, please re-add the field. Likewise, if you renamed a field, please rename it back to the original name. See here for more info on why they cannot be ignored.


Updating: Manually

Warning

This method is not recommended whatsoever. Furthermore, very limited support will be given if you attempt this method.

Click here to see the steps on how to update the note manually.

Sometimes, you may be able to update the card simply by re-installing the newer version of the .apkg. However, this has the main caveat where if any of the fields are added, renamed, repositioned or deleted between card versions, this will not work (and instead add a new version of JP Mining Note, e.g. named JP Mining Note-b320fa). Additionally, if you manually edited any of the fields, then this method will not work.

To see if the fields have been changed, compare the first two numbers in the version you want to install to the first two numbers of the current card version. If the first two numbers match, then you are likely safe to manually update the card.

If they don't match, then you MAY be able to get away with installing it anyways and transferring the old note types to the new note type. For example, a possible way to update the note is:

  1. Install the new version of the note.
  2. Select all the cards you want to transfer to the version, and change note type.
  3. Remove the old note type.
  4. Rename the new note type to the old note type name (JP Mining Note). See the changelog to see how the fields have changed and how you have to map the old fields to the new fields.

After Updating the Card

There may be further steps outside of just updating the card, such as updating Yomichan's templates / format. Further instructions on these are written below.

Afterwards, please see the final steps section.


Updating Yomichan's Anki Card Format

To update the Yomichan Format, the steps should be almost the same as the one specified already in the setup. The most important difference is that if a new field was added or a field has been renamed, then the field will not show up automatically in Yomichan.

Warning

Doing the above WILL clear all the fields that you previously had, unless there is a matching field in that other card.

Refreshing Yomichan Fields

Video Demo (click here)

  1. As always, create a backup of your Yomichan settings, just in case.
  2. After running install.py --update, create a temporary copy of the note by:
    Tools
    Manage Note Types
    Add
    → Select Clone: JP Mining NoteOk
    → Name the note anything you want (the following examples will use JP Mining Note copy) → Ok
    Close
  3. If you are currently viewing Yomichan Settings, please refresh the page.
  4. Head over to Anki Card Format as before.
  5. In the top right corner, change Model to JP Mining Note copy, and then change it back to JP Mining Note. (If you don't see JP Mining Note copy, please refresh the page.)
  6. Update the fields as specified.
    • It should be specified in the text you see when running install.py --update.
    • However, you should also simply compare the table on the setup page to your filled out fields.
  7. Remove the temporary note:
    Tools
    Manage Note Types
    → (select JP Mining Note copy)
    Delete

Explanation

Using the temporary copy of the updated card means that fields that remain unchanged between the old card and new card will be transferred automatically in the Yomichan Format. If you simply choose some random model like Basic, then almost none of the fields will be preserved, as the Basic card does not have any matching fields with the JP Mining Note model.


Updating Yomichan Templates

Like the above, you can simply follow the steps already specified in setup.

Again, please make a backup of your Yomichan settings just in case, and again, please make sure you reset the existing templates (unless you know what you are doing).

Note that your Yomichan template options will be reset if you follow all the steps. I recommend temporarily saving a copy of the Yomichan templates so you can easily reset your Yomichan template options after updating.


Updating the Runtime Options File

The runtime options does not automatically update with each note update, as to not override the user's configuration on each update. If the options file isn't updated, then the note will simply use the default value for the option.

However, if certain runtime options no longer work, you may have to update this file, as it is possible for the configuration file layout to have changed between versions. The most recent version of the options file can always be found here. if you want to update it.


Final Steps

By now, you should be done updating the note! Please do the following checks to make sure everything properly works:

  1. Preview an existing card, to ensure that nothing looks odd.
  2. Create a new card and make sure nothing looks odd.

    Example Japanese sentences to test card creation

Last update: November 23, 2022