imap-backup 14.4.4 → 14.5.0

data/lib/imap/backup/thunderbird/mailbox_exporter.rb

@@ -7,7 +7,11 @@ module Imap; end
 module Imap::Backup
   class Thunderbird; end
 
+  # Exports an account's emails to Thunderbird
   class Thunderbird::MailboxExporter
+    # @param email [String] an email address
+    # @param serializer [Serializer] a local folder backup
+    # @param profile [Thunderbird::Profile] an existing Thunderbird profile
     def initialize(email, serializer, profile, force: false)
       @email = email
       @serializer = serializer
@@ -15,6 +19,9 @@ module Imap::Backup
       @force = force
     end
 
+    # Copies the account's messages to the Thunderbird directory
+    # in the format expected by Thunderbird
+    # @return [void]
     def run
       if !profile_set_up
         error "The Thunderbird profile '#{profile.title}' " \
@@ -97,7 +104,7 @@ module Imap::Backup
       @local_folder ||= begin
         top_level_folders = [EXPORT_PREFIX, email]
         prefixed_folder_path = File.join(top_level_folders, serializer.folder)
-        ::Thunderbird::LocalFolder.new(profile, prefixed_folder_path)
+        ::Thunderbird::LocalFolder.new(profile: profile, path: prefixed_folder_path)
       end
     end
 

data/lib/imap/backup/uploader.rb

@@ -5,12 +5,17 @@ require "imap/backup/serializer"
 module Imap; end
 
 module Imap::Backup
+  # Uploads a backed-up folder
   class Uploader
+    # @param folder [Account::Folder] an online folder
+    # @param serializer [Serializer] a local folder backup
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer
     end
 
+    # Uploads messages that are present in the backup, but not in the online folder
+    # @return [void]
     def run
       if folder.uids.any?
         rename_serialized_folder

data/lib/imap/backup/version.rb

@@ -1,9 +1,14 @@
 module Imap; end
 
 module Imap::Backup
+  # @private
   MAJOR    = 14
-  MINOR    = 4
-  REVISION = 4
+  # @private
+  MINOR    = 5
+  # @private
+  REVISION = 0
+  # @private
   PRE      = nil
+  # The application version
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 14.4.4
+  version: 14.5.0
 platform: ruby
 authors:
 - Joe Yates
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-11-17 00:00:00.000000000 Z
+date: 2024-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -112,16 +112,16 @@ dependencies:
   name: thunderbird
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.0
+        version: 0.3.0
 description: Backup GMail, or any other IMAP email service, to disk.
 email:
 - joe.g.yates@gmail.com
@@ -133,10 +133,8 @@ files:
 - LICENSE
 - README.md
 - bin/imap-backup
-- docs/api.md
 - docs/delimiters-and-prefixes.md
-- docs/development.md
-- docs/migrate-server-keep-address.md
+- docs/documentation.md
 - docs/performance.md
 - imap-backup.gemspec
 - lib/imap/backup/account.rb
@@ -220,7 +218,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -235,8 +233,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.4.10
+signing_key: 
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk
 test_files: []

data/docs/api.md

@@ -1,20 +0,0 @@
-# @title Index
-# imap-backup API Documentation
-
-![Version](https://img.shields.io/gem/v/imap-backup?label=Version&logo=rubygems)
-[![Build Status](https://github.com/joeyates/imap-backup/actions/workflows/main.yml/badge.svg)][CI Status]
-![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/joeyates/b54fe758bfb405c04bef72dad293d707/raw/coverage.json)
-![License](https://img.shields.io/github/license/joeyates/imap-backup?color=brightgreen&label=License)
-[![Stars](https://img.shields.io/github/stars/joeyates/imap-backup?style=social)][GitHub Stars]
-
-[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml
-[GitHub Stars]: https://github.com/joeyates/imap-backup/stargazers "GitHub Stars"
-
-This is the developer documentation for imap-backup's **code**.
-
-Usage documentation is on [GitHub](https://github.com/joeyates/imap-backup).
-
-You can get an overview of the program's structure from the
-{file:ARCHITECTURE.md ARCHITECTURE} file.
-
-The {file:CHANGELOG.md CHANGELOG} has a history of the changes to the program.

data/docs/development.md

@@ -1,110 +0,0 @@
-# Repository
-
-After cloning the repo, run the following command to get
-better `git blame` output:
-
-```sh
-git config --local blame.ignoreRevsFile .git-blame-ignore-revs
-```
-
-# Design Goals
-
-* Secure - use a local configuration file protected by permissions
-* Restartable - calculate start point based on already downloaded messages
-* Standalone - do not rely on an email client or MTA
-
-# Testing
-
-## Feature Specs
-
-Specs under `specs/features` are integration specs.
-Some of these specs run against two local IMAP servers
-controlled by Podman (or Docker) Compose.
-
-Start them before running the test suite
-
-```sh
-$ podman-compose -f dev/compose.yml up -d
-```
-
-or, with Podman
-
-```sh
-$ podman-compose -f dev/compose.yml up -d
-```
-
-Then, run all specs
-
-```sh
-$ rspec
-```
-
-To exclude container-based tests
-
-```sh
-$ rspec --tag ~docker
-```
-
-To run **just** the feature specs
-
-```sh
-rspec spec/features/**/*_spec.rb
-```
-
-## Full Test Run
-
-The full test run includes RSpec specs **and** Runbocop checks
-
-```sh
-rake
-```
-
-# Older Rubies
-
-A Containerfile is available to allow testing with all available Ruby versions,
-see the README in the `dev` directory.
-
-# Performance Specs
-
-```sh
-PERFORMANCE=1 rspec --order=defined
-```
-
-Beware: the performance spec (just backup for now) takes a very
-long time to run, approximately 24 hours!
-
-### Debugging
-
-The feature specs are run 'out of process' via the Aruba gem.
-In order to see debugging output from the process,
-use `last_command_started.output`.
-
-## Access Docker imap server
-
-```ruby
-require "net/imap"
-require_relative "spec/features/support/30_email_server_helpers"
-
-include EmailServerHelpers
-
-test_connection = test_server_connection_parameters
-
-test_imap = Net::IMAP.new(test_connection[:server], test_connection[:connection_options])
-test_imap.login(test_connection[:username], test_connection[:password])
-
-message = "From: #{test_connection[:username]}\nSubject: Some Subject\n\nHello!\n"
-response = test_imap.append("INBOX", message, nil, nil)
-
-test_imap.examine("INBOX")
-uids = test_imap.uid_search(["ALL"]).sort
-
-fetch_data_items = test_imap.uid_fetch(uids, ["BODY[]"])
-```
-
-# Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request

data/docs/migrate-server-keep-address.md

@@ -1,47 +0,0 @@
-# Migrate to a new e-mail server while keeping your existing address
-
-While switching e-mail provider (from provider `A` to `B`),
-you might want to keep the same address (`mymail@domain.com`),
-and copy all your existing e-mails to your new server `B`.
-`imap-backup` can do that too!
-
-It is best to use [`imap-backup migrate`](/docs/commands/migrate.md)
-and not [`imap-backup restore`](/docs/commands/restore.md) here because
-`migrate` simply copies emails to folders with the same name as the ones
-they were downloaded from, while `restore` changes the names of restored
-folders if folders with the same name already exist on the destination server.
-
-1. Backup your e-mails: use [`imap-backup setup`](/docs/commands/setup.md)
-  to setup connection to your old provider `A`,
-  then launch [`imap-backup backup`](/docs/commands/backup.md).
-1. Actually switch your e-mail service provider (update your DNS MX and all that...).
-1. As both the source and the destination have the same address,
-  you need to manually rename your old account first:
-
-    1. Modify your configuration file manually
-      (i.e. not via `imap-backup setup`) and
-      rename your account to `mymail-old@domain.com`:
-
-        ```diff
-          "accounts": [
-            {
-        -     "username": "mymail@domain.com",
-        +     "username": "mymail-old@domain.com",
-              "password": "...",
-        -     "local_path": "/some/path/.imap-backup/mymail_domain.com",
-        +     "local_path": "/some/path/.imap-backup/mymail-old_domain.com",
-              "folders": [...],
-              "server": "..."
-            }
-        ```
-
-    1. Rename the backup directory from `mymail_domain.com`
-      to `mymail-old_domain.com`.
-
-1. Set up a new account giving access to the new provider `B`
-  using `imap-backup setup`.
-1. Now you can use `imap-backup migrate`, optionally adapting
-  [delimiters and prefixes configuration](/docs/delimiters-and-prefixes.md)
-  if need be:
-
-		imap-backup migrate mymail-old@domain.com mymail@domain.com [options]