Add MIGRATION.md migration guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,4 +5,5 @@
 - [ ] Run `bundle exec rubocop` to test for code style violations and recommendations
 - [ ] Add Unit Tests (aka `specs/*_spec.rb`) if applicable
 - [ ] Run `bundle exec rspec` to run the whole test suite and ensure all your tests pass
-- [ ] Make sure you added an entry in [the `CHANGELOG.md` file](https://github.com/wordpress-mobile/release-toolkit/blob/trunk/CHANGELOG.md#trunk) to describe your changes under the approprioate existing `###` subsection of the existing `## Trunk` section.
+- [ ] Make sure you added an entry in [the `CHANGELOG.md` file](https://github.com/wordpress-mobile/release-toolkit/blob/trunk/CHANGELOG.md#trunk) to describe your changes under the appropriate existing `###` subsection of the existing `## Trunk` section.
+- [ ] If relevant, please add an entry in [the `MIGRATION.md` file](https://github.com/wordpress-mobile/release-toolkit/blob/trunk/MIGRATION.md#migrating-to-trunk) to provide more context for a version migration impacted by the changes in this pull request, in the appropriate `###` subsection of the existing `## Migrating to Trunk` section.

CHANGELOG.md

@@ -7,6 +7,9 @@
 ### Breaking Changes
 
 - Remove the `skip_glotpress` parameter from the `ios_bump_version_release` action [#443]
+- Add the `public_version_xcconfig_file` parameter to the `ios_get_app_version` action to replace the need for an environment variable [#445]
+- Remove the `ios_localize_project` and `ios_update_metadata` actions [#447]
+- Remove the `skip_deliver` parameter from `ios_bump_version_hotfix` and `ios_bump_version_release` actions [#450]
 
 ### New Features
 
@@ -20,6 +23,7 @@ _None_
 ### Internal Changes
 
 - Updates `activesupport` to `6.1.7.1`, addressing [a security issue](https://github.com/advisories/GHSA-j6gc-792m-qgm2). This is a major version change, but as the dependency is internal-only, it shouldn't be a breaking change for clients. [#441]
+- Add the explicit dependency to `xcodeproj (~> 1.22)`, used in this case to replace the previous manual parsing of `.xcconfig` files. [#451]
 
 ## 6.3.0
 

Gemfile.lock

@@ -16,6 +16,7 @@ PATH
       progress_bar (~> 1.3)
       rake (>= 12.3, < 14.0)
       rake-compiler (~> 1.0)
+      xcodeproj (~> 1.22)
 
 GEM
   remote: https://rubygems.org/

MIGRATION.md

@@ -0,0 +1,20 @@
+# Release Toolkit Migration Guide
+
+---
+
+## Migrating to Trunk
+
+### Considerations for breaking changes
+
+- Ensure that calls to `ios_bump_version_release` already passed `skip_glotpress: true`.
+In case of passing false as parameter or not providing a value (false being the default for this ConfigItem), you'll have to ensure that:
+  - `download_metadata.swift` isn't being used; if it is, it's a good time to migrate to the new tooling
+  - You're not relying on `ios_bump_version_release` for commiting the `.po/.pot` file
+- The deprecated actions `ios_localize_project` and `ios_update_metadata` were now completely removed. If your project is still using them, please use the new tooling instead.
+  - See `ios_generate_strings_file_from_code`, `ios_extract_keys_from_strings_files`, `ios_download_strings_files_from_glotpress` and `ios_merge_strings_files` for typical replacements.
+- The action `ios_get_app_version` now requires a parameter `public_version_xcconfig_file` with the public `.xcconfig` file path instead of relying on the environment variable `PUBLIC_CONFIG_FILE`. While the complete removal of this environment variable is our goal, at this point it is still required by other actions such as `ios_bump_version_release` and `ios_codefreeze_prechecks`.
+- The usage of a `Deliverfile` (including its `app_version`) is discouraged -- please use `upload_to_app_store` directly from your `Fastfile` instead. Therefore, the parameter `skip_deliver` from the actions `ios_bump_version_hotfix` and `ios_bump_version_release` has been removed.
+
+### Clean-ups
+
+- You can now delete the `ENV['APP_STORE_STRINGS_FILE_NAME']` from your Fastfile, as it isn't being used anymore.

fastlane-plugin-wpmreleasetoolkit.gemspec

@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'progress_bar', '~> 1.3'
   spec.add_dependency 'rake', '>= 12.3', '< 14.0'
   spec.add_dependency 'rake-compiler', '~> 1.0'
+  spec.add_dependency 'xcodeproj', '~> 1.22'
 
   # `google-cloud-storage` is required by fastlane, but we pin it in case it's not in the future
   spec.add_dependency 'google-cloud-storage', '~> 1.31'

lib/fastlane/plugin/wpmreleasetoolkit/actions/ios/ios_bump_version_beta.rb

@@ -15,7 +15,7 @@ def self.run(params)
         Fastlane::Helper::Ios::VersionHelper.update_xc_configs(@new_beta_version, @short_version, @new_internal_version)
         UI.message 'Done!'
 
-        Fastlane::Helper::Ios::GitHelper.commit_version_bump(include_deliverfile: false, include_metadata: false)
+        Fastlane::Helper::Ios::GitHelper.commit_version_bump()
       end
 
       #####################################################

lib/fastlane/plugin/wpmreleasetoolkit/actions/ios/ios_bump_version_hotfix.rb

@@ -9,18 +9,11 @@ def self.run(params)
         create_config(params[:previous_version], params[:version])
         show_config()
 
-        update_deliverfile = params[:skip_deliver] == false
-        if update_deliverfile
-          UI.message 'Updating Fastlane deliver file...'
-          Fastlane::Helper::Ios::VersionHelper.update_fastlane_deliver(@new_short_version)
-          UI.message 'Done!'
-        end
-
         UI.message 'Updating XcConfig...'
         Fastlane::Helper::Ios::VersionHelper.update_xc_configs(@new_version, @new_short_version, @new_version_internal)
         UI.message 'Done!'
 
-        Fastlane::Helper::Ios::GitHelper.commit_version_bump(include_deliverfile: update_deliverfile, include_metadata: false)
+        Fastlane::Helper::Ios::GitHelper.commit_version_bump()
 
         UI.message 'Done.'
       end
@@ -51,16 +44,6 @@ def self.available_options
             description: 'The version to branch from',
             is_string: true
           ),
-          FastlaneCore::ConfigItem.new(
-            key: :skip_deliver,
-            env_name: 'FL_IOS_BUMP_VERSION_HOTFIX_SKIP_DELIVER',
-            description: 'Skips Deliverfile key update',
-            is_string: false, # Boolean parameter
-            optional: true,
-            # Don't skip the Deliverfile by default. At the time of writing, 2 out of 3 consumers
-            # still have a Deliverfile.
-            default_value: false
-          ),
         ]
       end
 

lib/fastlane/plugin/wpmreleasetoolkit/actions/ios/ios_bump_version_release.rb

@@ -21,18 +21,11 @@ def self.run(params)
         Fastlane::Helper::GitHelper.create_branch(@new_release_branch, from: default_branch)
         UI.message 'Done!'
 
-        UI.message 'Updating Fastlane deliver file...' unless params[:skip_deliver]
-        Fastlane::Helper::Ios::VersionHelper.update_fastlane_deliver(@new_short_version) unless params[:skip_deliver]
-        UI.message 'Done!' unless params[:skip_deliver]
-
         UI.message 'Updating XcConfig...'
         Fastlane::Helper::Ios::VersionHelper.update_xc_configs(@new_version, @new_short_version, @new_version_internal)
         UI.message 'Done!'
 
-        Fastlane::Helper::Ios::GitHelper.commit_version_bump(
-          include_deliverfile: !params[:skip_deliver],
-          include_metadata: false
-        )
+        Fastlane::Helper::Ios::GitHelper.commit_version_bump()
 
         UI.message 'Done.'
       end
@@ -51,11 +44,6 @@ def self.details
 
       def self.available_options
         [
-          FastlaneCore::ConfigItem.new(key: :skip_deliver,
-                                       env_name: 'FL_IOS_CODEFREEZE_BUMP_SKIPDELIVER',
-                                       description: 'Skips Deliver key update',
-                                       type: Boolean,
-                                       default_value: false),
           FastlaneCore::ConfigItem.new(key: :default_branch,
                                        env_name: 'FL_RELEASE_TOOLKIT_DEFAULT_BRANCH',
                                        description: 'Default branch of the repository',

lib/fastlane/plugin/wpmreleasetoolkit/actions/ios/ios_get_app_version.rb

@@ -4,9 +4,8 @@ class IosGetAppVersionAction < Action
       def self.run(params)
         require_relative '../../helper/ios/ios_version_helper'
 
-        UI.user_error!('You need to set at least the PUBLIC_CONFIG_FILE env var to the path to the public xcconfig file') unless ENV['PUBLIC_CONFIG_FILE']
-
-        Fastlane::Helper::Ios::VersionHelper.get_public_version
+        public_version_xcconfig_file = params[:public_version_xcconfig_file]
+        Fastlane::Helper::Ios::VersionHelper.get_xcconfig_public_version(xcconfig_file: public_version_xcconfig_file)
       end
 
       #####################################################
@@ -22,7 +21,15 @@ def self.details
       end
 
       def self.available_options
-        # Define all options your action supports.
+        [
+          FastlaneCore::ConfigItem.new(
+            key: :public_version_xcconfig_file,
+            env_name: 'FL_IOS_PUBLIC_VERSION_XCCONFIG_FILE',
+            description: 'Path to the .xcconfig file containing the public app version',
+            type: String,
+            optional: false
+          ),
+        ]
       end
 
       def self.output

lib/fastlane/plugin/wpmreleasetoolkit/helper/ios/ios_git_helper.rb

@@ -8,68 +8,15 @@ module GitHelper
         #
         # This typically commits and pushes:
         #  - The files in `./config/*` – especially `Version.*.xcconfig` files
-        #  - The `fastlane/Deliverfile` file (which contains the `app_version` line)
-        #  - The `<ProjectRoot>/<ProjectName>/Resources/AppStoreStrings.pot` file, containing a key for that version's release notes
         #
         # @env PROJECT_ROOT_FOLDER The path to the git root of the project
-        # @env PROJECT_NAME The name of the directory containing the project code (especially containing the Resources/ subfolder)
         #
-        # @param [Bool] include_deliverfile If true (the default), includes the `fastlane/Deliverfile` in files being commited
-        # @param [Bool] include_metadata If true (the default), includes the `fastlane/download_metadata.swift` file and the `.pot` file (which typically contains an entry or release notes for the new version)
-        #
-        def self.commit_version_bump(include_deliverfile: true, include_metadata: true)
-          files_list = [File.join(ENV['PROJECT_ROOT_FOLDER'], 'config', '.')]
-          files_list.append File.join('fastlane', 'Deliverfile') if include_deliverfile
-          if include_metadata
-            files_list.append File.join('fastlane', 'download_metadata.swift')
-            files_list.append File.join(ENV['PROJECT_ROOT_FOLDER'], ENV['PROJECT_NAME'], 'Resources', ENV['APP_STORE_STRINGS_FILE_NAME'])
-          end
+        def self.commit_version_bump
+          files_list = [File.join(get_from_env!(key: 'PROJECT_ROOT_FOLDER'), 'config', '.')]
 
           Fastlane::Helper::GitHelper.commit(message: 'Bump version number', files: files_list, push: true)
         end
 
-        # Calls the `Scripts/localize.py` script in the project root folder and push the `*.strings` files
-        #
-        # That script updates the `.strings` files with translations from GlotPress.
-        #
-        # @env PROJECT_ROOT_FOLDER The path to the git root of the project
-        # @env PROJECT_NAME The name of the directory containing the project code (especially containing the `build.gradle` file)
-        #
-        # @deprecated This method is only used by the `ios_localize_project` action, which is itself deprecated
-        #             in favor of the new `ios_generate_strings_file_from_code` action
-        # @todo [Next Major] Remove this method once we fully remove `ios_localize_project`
-        #
-        def self.localize_project
-          Action.sh("cd #{get_from_env!(key: 'PROJECT_ROOT_FOLDER')} && ./Scripts/localize.py")
-
-          Fastlane::Helper::GitHelper.commit(message: 'Update strings for localization', files: strings_files, push: true) || UI.message('No new strings, skipping commit')
-        end
-
-        # Call the `Scripts/update-translations.rb` then the `fastlane/download_metadata` Scripts from the host project folder
-        #
-        # @env PROJECT_ROOT_FOLDER The path to the git root of the project
-        # @env PROJECT_NAME The name of the directory containing the project code (especially containing the `build.gradle` file)
-        #
-        # @todo Migrate the scripts, currently in each host repo and called by this method, to be helpers and actions
-        #       in the release-toolkit instead, and move this code away from `ios_git_helper`.
-        #
-        def self.update_metadata
-          Action.sh("cd #{get_from_env!(key: 'PROJECT_ROOT_FOLDER')} && ./Scripts/update-translations.rb")
-
-          Fastlane::Helper::GitHelper.commit(message: 'Update translations', files: strings_files, push: false)
-
-          Action.sh('cd fastlane && ./download_metadata.swift')
-
-          Fastlane::Helper::GitHelper.commit(message: 'Update metadata translations', files: './fastlane/metadata/', push: true)
-        end
-
-        def self.strings_files
-          project_root = get_from_env!(key: 'PROJECT_ROOT_FOLDER')
-          project_name = get_from_env!(key: 'PROJECT_NAME')
-
-          Dir.glob(File.join(project_root, project_name, '**', '*.strings'))
-        end
-
         def self.get_from_env!(key:)
           ENV.fetch(key) do
             UI.user_error! "Could not find value for \"#{key}\" in environment."