Notes on Migrating an iPhoto Library from iPhoto to Photos for Mac

Your migration from iPhoto to Photos will be smoother, if you take a few precautions.Get started with Photos for OS X - Apple Support, also see: Updating from iPhoto to Photos for macOS (archive copy). (this link is broken: Updating from iPhoto to Photos for OS X - Apple Support)

And: Wayback Machine: How Photos handles content and metadata from iPhoto and Aperture https://web.archive.org/web/20190515155043/https://support.apple.com/en-us/HT204478

Before the migration:

1. Backup: First of all, as always, when upgrading the system, make a full backup, so you can revert to the previous state. Make a Time Machine backup or a bootable clone.
2. Prepare the library: Ensure that your iPhoto Library has no issues before the migration. Repair the permissions, and repair the database. http://ilifehelp.com/tutorials/iPhoto/rebuild/How.to.rebuild.repair.iPhoto.html
3. Prepare the volume: If your iPhoto Library is not in your Pictures folder, but on an external drive, check the drive for compatibility. Photos may have problems accessing the drive, if it is on a network volume and not locally mounted. If you are planning to use the library with iCloud Photo Library, the drive must be formatted MacOS Extended (Journaled). Move your iPhoto Library to a correctly formatted locally mounted volume, if necessary. Even if you do not want to use iCloud Photo Library, the migration will only work on a correctly formatted drive. (https://support.apple.com/en-us/HT201517)
4. Use only locally mounted volumes for the Photos Library: Just like iPhoto or Aperture, the Photos Library cannot be stored in a Cloud storage like Drop Box, iCloud Drive, Google Drive (Updating from iPhoto to Photos for OS X - Apple Support). Syncing will corrupt the Photos Library.
5. Metadata - Places: The new Photos.app does not support geotagging as well as iPhoto. The maps are not detailed enough to position the pins correctly, you cannot name places, and you cannot copy locations from one photo and paste the locations onto other photos. If you have photos in your iPhoto Library, that do not yet have GPS locations assigned, add the locations while your library is still in iPhoto. In Photos you will have to fall back on an AppleScript (Script: Copy GPS tags from one Photo to Other Photos).
6. Metadata - Titles: The batch changing support is still not as good as in iPhoto. If you need to batch change titles or captions, do it in iPhoto, while you can. Batch changing in Photos is very limited. Most importantly, Photos 1 to Photos 3 does not use the filenames as default titles, only titles in the title field. If you want to see the filenames below the thumbnails in Photos like in iPhoto, batch change the titles to the filenames, while you are still running iPhoto. (or use later an AppleScript: Script: Changing the Title to the Filename without Extension) Photos 4.0 and Photos 5.0 can show the filenames below the thumbnails, but you cannot copy and paste them there, only titles.
7. Events vs. Moments: Photos does not have events, but structures the library by Moments and Collections (Photos 1 to Photos 4) or Months and Days (Photos 5), which are created automatically, based on the locations and capture dates. It is important to check the dates and locations for consistency, before you migrate. Later it might be difficult to correct them.
8. Descriptions of Albums: Albums and events will be transferred as albums, but Photos has no description field for the albums. If you need to save descriptions of your albums or events, copy them to the description field of the photos in the albums. Since Photos does not have events, smart albums based on events will not be transferred to Photos.
9. Smart albums: See: How Photos displays Smart Albums from iPhoto or Aperture - Apple Support Smart albums using keyword rules "keyword start with ...", keyword ends with ...", "keyword contains ...", will also not be migrated to Photos correctly as pointed out by the user daiya49, see this discussion: Re: Smart Albums lost keyword criteria when imported from iPhoto to Photos . See here, what will migrate and what not: How Photos handles content and metadata from iPhoto and Aperture - Apple Support
10. Referenced Originals: Photos does support referenced files, and a bit better than iPhoto, but photos with referenced originals cannot be used with iCloud Photo Library. But Photos has no tools to relocate originals to another volume. You cannot turn managed photos into referenced photos. I would stick with a managed library.
11. Merge your libraries before the migration: Photos does not support the merging of libraries. If you want to merge several libraries into one, do that before you migrate your libraries, for example with Aperture 3 (Aperture 3.3: How to use Aperture to merge iPhoto libraries), if you have it, or the paid version of iPhoto Library Manager http://www.fatcatsoftware.com/iplm/Help/merging%20libraries.html

During the Migration

1. Storage for the new Photos Library: Your new Photos library will be created in the same folder as your original iPhoto Library. Make sure, you have free storage in that location. Photos will not duplicate your original image files from the iPhoto Library, but link to these files to save space: https://web.archive.org/web/20190502225116/https://support.apple.com/en-us/HT204476 (old, broken link: Photos saves disk space by sharing images with your iPhoto or Aperture libraries - Apple Support)
2. Pick the correct iPhoto Library for the Migration: Photos will migrate the last iPhoto Library you opened before the migration automatically. So switch to the iPhoto library you want to migrate, before you open Photos for the first time.

After the Migration:

1. Don't delete your old iPhoto Library in a hurry. It does not need much space, and you may need to revert to it, if the migration will not succeed.
2. If you are missing photos after the migration: https://support.apple.com/en-gb/HT204887
3. User tips for Photos for Mac: Thematic Index to Photos for Mac related … - Apple Community

BTW: There is no need to do the migration in a hurry, if you are still running Mojave. Both Aperture3.6 and iPhoto 9,6.1 are supported on OS X Yosemite and OS X El Capitan, Sierra, High Sierra (some minor issues, and you can no longer order print Products from Aperture) and Mojave. You can continue to use Aperture 3.6 or iPhoto 9.6.1, while you are exploring Photos, so you will know, how to prepare best for the migration. Do the migration before you upgrade to macOS 10.15. Neither iPhoto nor Aperture can run on macOS 15, Catalina. Migrate your Aperture libraries to Photos or Adobe Lightroom Classic - Apple Support

This User Tip by Old Toad lists the differences between iPhoto and Photos as a check list. It can help you decide, if you should migrate to Photos or not: Photos 3.0 vs iPhoto 9.6.1: Features and Capabilities

Good Luck!