Swiftpack.co - Package - SDGGiesbrecht/Workspace

macOS • Linux

Documentation

Workspace

Workspace automates management of Swift projects.

Πᾶν ὅ τι ἐὰν ποιῆτε, ἐκ ψυχῆς ἐργάζεσθε, ὡς τῷ Κυρίῳ καὶ οὐκ ἀνθρώποις.

Whatever you do, work from the heart, as working for the Lord and not for men.

―⁧שאול⁩/Shaʼul

Features

The Workspace Workflow

(The following sample package is a real repository. You can use it to follow along.)

When the Repository Is Cloned

The need to hunt down workflow tools can deter contributors. On the other hand, including them in the repository causes a lot of clutter. To reduce both, when a project using Workspace is pulled, pushed, or cloned...

git clone https://github.com/SDGGiesbrecht/SamplePackage

...only one small piece of Workspace comes with it: A short script called “Refresh” that comes in two variants, one for each operating system.

Hmm... I wish I had more tools at my disposal... Hey! What if I...

Refresh the Project

To refresh the project, double‐click the Refresh script for the corresponding operating system. (If you are on Linux and double‐clicking fails or opens a text file, see here.)

Refresh opens a terminal window, and in it Workspace reports its actions while it sets the project folder up for development. (This may take a while the first time, but subsequent runs are faster.)

This looks better. Let’s get coding!

[Add this... Remove that... Change something over here...]

...All done. I wonder if I broke anything while I was working? Hey! It looks like I can...

Validate Changes

When the project seems ready for a push, merge, or pull request, validate the current state of the project by double‐clicking the Validate script.

Validate opens a terminal window and in it Workspace runs the project through a series of checks.

When it finishes, it prints a summary of which tests passed and which tests failed.

Oops! I never realized that would happen...

Summary

  1. Refresh before working.
  2. Validate when it looks complete.

Wow! That was so much easier than doing it all manually!

Applying Workspace to a Project

To apply Workspace to a project, run the following command in the root of the project’s repository. (This requires a full install.)

$ workspace refresh

By default, Workspace refrains from tasks which would involve modifying project files. Such tasks must be activated with a configuration file.

Installation

Workspace provides command line tools.

They can be installed any way Swift packages can be installed. The most direct method is pasting the following into a terminal, which will either install or update them:

curl -sL https://gist.github.com/SDGGiesbrecht/4d76ad2f2b9c7bf9072ca1da9815d7e2/raw/update.sh | bash -s Workspace "https://github.com/SDGGiesbrecht/Workspace" 0.21.3 "workspace help" workspace arbeitsbereich

Importing

Workspace provides a library for use with the Swift Package Manager.

Simply add Workspace as a dependency in Package.swift:

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/SDGGiesbrecht/Workspace", .upToNextMinor(from: Version(0, 21, 3))),
    ],
    targets: [
        .target(name: "MyTarget", dependencies: [
            .productItem(name: "WorkspaceConfiguration", package: "Workspace"),
        ])
    ]
)

The library’s module can then be imported in source files:

import WorkspaceConfiguration

About

The Workspace project is maintained by Jeremy David Giesbrecht.

If Workspace saves you money, consider giving some of it as a donation.

If Workspace saves you time, consider devoting some of it to contributing back to the project.

Ἄξιος γὰρ ὁ ἐργάτης τοῦ μισθοῦ αὐτοῦ ἐστι.

For the worker is worthy of his wages.

―‎ישוע/Yeshuʼa

Github

link
Stars: 42
Help us keep the lights on

Dependencies

Releases

0.21.3 - Jul 23, 2019

Bug Fixes

Dependency updates.

0.21.2 - Jul 12, 2019

Bug Fixes

Dependency updates.

0.21.1 - Jul 4, 2019

Bug Fixes

  • The filenames of GitHub templates now use Unicode directly. (Since GitHub handles them properly now.)

0.21.0 - Jun 14, 2019

Breaking Changes

  • Localized symbol documentation is fully implemented. Documenting with multiple localizations active requires that each symbols has a documentation comment for every localization, or that the symbol itself is localized and cross‐referenced its equivalents. See the localization option for more details.
  • API documentation and read‐me generation have been unified.
    • Front matter is available along with the generated API documentation in addition to the read‐me.
    • The read‐me now automatically includes the package documentation comment parsed from the manifest.
    • Localized read‐me files and related project lists have been moved completely into the generated documentation. (The root‐level README.md remains behind for GitHub.)
    • Related configuration options have been rearranged:
      • The description, features, and example usage are no longer part of the configuration. They now belong in the documentation comment in the package manifest.
      • The installation instructions, import instructions and about sections are now directly on the .documentation property (instead of under .documentation.readMe), since they now apply to both the read‐me and the generated documentation.
  • GitHub management is localized:
    • Contributing instructions.
    • Issue templates.
  • OperatingSystem has been renamed to Platform to match the PackageDescription API.

New Features

  • Documentation now includes the command line interface of executable products built on SDGCommandLine.
  • Test manifests are updated during testing when running:
    • on a platform which can generate them, and
    • for a project which declares support for a platform which needs test manifests.

Bug Fixes

  • Protocol documentation can be filtered by protocol requirements or customization points.
  • @unknown switch cases are exempt from test coverage by default.

0.20.0 - May 4, 2019

Breaking Changes

  • Test coverage can be checked using the package manager without Xcode, including on Linux!.
    • Since the Xcode job would now be redundant, it has been removed and the package manager job renamed to simply macos.
  • Manual documentation inheritance only works within a single package. It no longer copies documentation from dependencies. This is more in line with copyright and licensing laws. (Cross‐package inheritance is still respected in coverage validation and other situations which involve only reading, not copying the unowned documentation.)

New Features

  • Documentation can be sped up by configuring ignored dependencies.