There Is No Support for Multipackage Repositories

As of this writing, a git repository can only have one Swift Package, meaning you need to create a repository for each Swift Package you want to share.

So, while setting up remote Swift Packages may sound like a big hassle, it gives you the ability to maintain each package separately, with different developers and different access controls.

Putting your Swift Packages on public repositories gives you another interesting opportunity – make some of your logic an open source library. An open source library can let other developers worldwide help you maintain your code without exposing them to other parts of your app.

Versioning

Versioning is a pain point, relevant not only for Swift Packages but also for any external library you implement in your project.

The first stage of writing a library and adding it to your project is relatively easy. It is similar to adding a new set of classes to your app.

Once your library is shared across multiple projects, we assume that it is not standing still and evolves based on project requirements over time.

Remember that a first-party library is not a classic product – we (that is to say, an app) demand modifications or add-ons, and then we implement them into our library.

The described process may cause us backward compatibility with other apps and projects depending on that library.

The issue gets even worse when different projects and even other libraries are dependent on that particular library we just changed.

The fact that we manage each library independently, in its git repository, and potentially with many developers (since it’s public) makes the backward compatibility problem a real issue we need to deal with.

Remember, Public Is Public

Some of our packages contain sensitive information we don’t want to expose to the world.

Some of them are not even relevant to other developers around the world.

This means that making some of our code an open source project is not always what we want, so what do we do?

In previous chapters, we learned how to decouple modules in our code and use different design patterns to do it.

The same approach can be used in this case to take out some private information and then enjoy the benefits of sharing your code.

The leading principle here (again) is SoC (“separation of concerns ”) – separating the private information from the package itself lets you put the package on a public repository in the future.

Not only can separating private information help you make your package public, but it can also make it more reusable and testable.

For instance, let’s take our networking package. Instead of putting the list of endpoints inside the package, we can separate them into a different file hosted by the app. Take a look at Figure 6-1.

The Endpoints.plist contains all the endpoints and their HTTP request methods (Figure 6-2).

Now, this is an example of how to take a private package and make it public.

The conversion to a public repository reduces complexity and can give you additional benefits of better design and faster bug fixes.

Distribute Your Package

In general, the fact that your package repository is public and not private means it is already available for others to clone and integrate it into their projects.

There is no need to do additional steps for that to happen.

There is no “official” Swift Package index at the time of this writing, even though there are some suggestions in the Swift developer’s community to create one.

Searching from Xcode for a Swift Package will find your package (or other public packages) as long as it is public. But a real, official index does not yet exist.

However, there are some alternative indexes where you can find many Swift Packages to use. The most famous one is https://swiftpackageindex.com, containing thousands of public Swift Packages for you to use.

It has a great search engine and full detailed information for each package. I recommend you add your package to that index or any other index, for that matter.

Readme.md File

We didn’t talk about the Readme.md file yet, and perhaps now is the time for that.

There are three different aspects we document our package – the first is comments, which provide relevant documentation while coding, and we discussed that in previous chapters. The second is unit tests that other than making sure our package performs as expected are part of the documentation.

The third is the Readme.md file.

The Readme.md file is the first file git hosting services show when a developer entered the repository.

Readme.me file acts as a “manual” and contains useful package information, such as

• Package goal

• Installation details

• Setup steps

• Usage

• Different notes

The Readme.md file is important in private repositories as well, but in public repositories, it is critical documentation.

Remember that your package may contain many Swift files. Documenting every public interface using comments is excellent, but it doesn’t answer the developer question “What is the ‘main’ file?”

In other words, the one question every Readme.md file should answer is “How do I start?”

As I said, even in private packages, that information can be important while we share it with other developers in our team or even forget that ourselves.

Readme.md File Location and Formatting

The Readme.md file should be located in the root folder of your package, but don’t worry about that – when creating a new Swift Package, a Readme.md file is automatically generated for you.

In Figure 6-3, you can see part of the Readme.md file of FMDB Swift Package.

As you can see from Figure 6-3, the Readme.md file is not a plain text document. The “md” extension refers to “MarkDown,” and it is elementary to create a well rich, documented file for your library.

Readme.md Markdown Formatting

The Readme.md markdown formatting is probably one of the most straightforward formats that exist.

Some basic rules:

One hash mark (#) at the beginning of the sentence produces a title.

Adding more hash marks (“##”, “###”) adds headers in different sizes correspondingly.

A sequence of three apostrophes (```) is used to start a code snippet, and another series of three apostrophes are used to close the code snippet.

Adding a link is done using the following format: [<Displayed name>](URL).

For example:

[Apple Inc](www.apple.com)

You can also make the text richer:

Bold – **This is bold text** (This is bold text)

Italic – *Italic text* (Italic text)

Strikethrough – ~~This is a strikethrough text~~ (This is a strikethrough text)

Creating lists – You can use the same symbols you generally use to create lists, such as -, a digit, or *.

You can even insert images and GIF animations to your Readme.md file quite easily by using the link formatting I mentioned previously.

Figure 6-4 shows an example of a Readme.md source file and how it looks on GitHub.

Unlike HTML, the markup language used in Readme.md files is straightforward and clear even in the source version.

Readme.md Best Practices

The Readme.md formatting is not the most crucial part of the file, but rather its content.

Most Readme.md files are structured into sections, describing the different package’s areas implementation and usage.

Here are some of the sections that are recommended to be included in your Readme.md file:

Overview – Describing in short what the package does and what it aims to solve.

What’s new? – Describe what’s new in the latest release. Update this section with every release.

Requirements – Usually what platforms and minimum versions are required for the package to be installed. This can be corresponding to what is written in the Package.swift file.

Install – Necessary steps for the developer to add the package to its project. If you support other dependencies’ managers, this is the place to mention that.

Setup – If there’s some initialization needed to start using the package code, you write it under “Setup.” It is best to include a code snippet.

Usage, examples, and tips – Take the primary use cases and demonstrate how to use your package in each one of them.

History – Document here primary releases or maybe the origin of the code if it was part of another project or library.

Contributors – List of developers that have a central role in working on the library.

Support and bugs – What to do in case of a problem? How to open an issue?

You don’t have to add all the preceding sections, but this list can give you a good picture of how Readme.md files are built and what types of information are expected to be included.

Adding Pictures and Animations

Another good way to demonstrate your package, which many developers ignore, is visual explanations.

In case your package deals with UI elements, you can add images to your Readme.md files to show how it performs. Not only that, but you can also add GIF animations to show the UI behavior.

Besides “eye-catching,” adding visual content also helps you explain what your package does better than any words.

To add images or GIF animations, you can use the markdown formatting rules mentioned previously.

What Is the Problem Exactly?

The problem is, of course, access control.

When you connect your private dependency to your project, Xcode takes care of the credentials for you. It will probably ask you for a username and password and will save it for later use.

But this approach has two main issues.

First, it doesn’t work when your (private) package is a dependency for other packages and not your app.

Second, this method works only on your machine and is based on your private git account.

When working in a team, this could be an issue, and the problem gets even more prominent when we try to implement that in a CI machine.

Fortunately , there are two primary ways to solve that – personal access token and ssh.

Personal Access Token

First, I’ll start by saying that “personal access token” (let’s call it PAT from now on) is not the recommended way to give access to private repositories in git, but it’s indeed the simplest way.

Generating New Token in Git

To generate a new PAT, we go to GitHub personal menu and choose “Settings” (Figure 6-5).

From the menu on the left, choose “Developer settings” (Figure 6-6).

And then choose “Personal access tokens” (Figure 6-7).

In Figure 6-7, you can see a button named “Generate new token,” which will generate a new token for you to use.

The good thing about PAT is the fact that we can limit the token’s access level (see Figure 6-8).

In the case of Swift Packages, all you need to mark is the first scope (“repo”), and that’s all.

After generating the token, you’ll see the token itself, and you should copy it to somewhere else because that’s the last time it is exposed to you.

Now that we have the token, we can incorporate it in the package dependency URL, as follows:

.package(url: "https://<token>:[email protected]/<username>/<repository_name>", .branch("main"))

This should work for other developers as well and even on CI machine.

Using SSH

Using SSH is probably the best-secured method for using private Swift Packages with multiple developers, CI machines, and so on.

Unlike a personal access token, using SSH requires a little more work to set up, but it works flawlessly once you set it up.

Adding the Public Key to GitHub

After generating two keys – private and public – we added the private key to our ssh-agent, so it can use it to authenticate with our git server.

What we need to do next is to add the public key to our git server, so it will have “the lock” we talked about.

So, let’s go to our package repository in GitHub and select “Settings ➤ Deploy keys” (see Figure 6-9).

Tap on Add deploy key, and you’ll see two fields – title and key (Figure 6-10).

Besides the title field, you can see that the key field expects to type some text inside. That should be the content of the public key you generated earlier.

To easily copy it, go to the Terminal, and type the following command:

pbcopy < ~/.ssh/id_ed25519.pub

What pbcopy does is copy the content of the provided file to the system clipboard.

Once you have the public key content in your clipboard, pass it to the key field, and press “Add key.”

What Is a Monorepo?

You probably heard the term Monorepo here and there.

That’s because many big companies use it – Facebook, Google, Uber, and more.

The idea behind Monorepo is that instead of putting each project and each library in a repository of its own, we put them all in the same repository (see Figure 6-11).

While this idea may sound a little bit weird at first, it has several significant advantages.

Dependencies’ Management Can Be Simpler

I want to emphasize the phrase “Can Be” because, in many cases and small- and medium-scale repositories, that’s the situation.

The fact that all libraries are in the same repository doesn’t make dependencies’ management unnecessary, but it can make it much simpler.

The preceding structure is just a suggestion, but you can easily see what we did there.

We created a folder named Packages and put each Swift Package into its folder.

On the same level of the folder Packages, we created the two projects (can be more) side by side.

The Packages folder and the two projects are all inside the Monorepo.

To create dependencies between packages, all we need to do in our Package.swift file is to point to a local package as a dependency.

Looking at the preceding dependency requirement, you see how easy it is to create local dependencies when all the packages are located in the same repository.

Cross-Project Changes Are Easier

Imagine the following scenario – we have two projects and two libraries with a local dependency (just like we saw in the previous section). Now, we want to do an API change in one of the libraries on which both projects are dependent.

The library API changes require us to change code in both projects and verify everything works as expected.

Doing that in a polyrepo (a strategy where all projects and libraries have their repository) requires us to clone different repositories, modify the code, push it back, resolve the remote package again, and verify everything is stable.

And to overcome a situation where we push untested code to the main branch or a stable version, we need to check out a branch in the library repository, point the dependency requirement to the new branch, and then merge everything.

You can see the hassle that we have when all we want to do is change a simple API, which was a “simple” scenario.

In the case of Monorepo, this situation is easily handled, with changes being done quickly across all projects and libraries together.

How to Move Forward with Only One Project?

One question often asked when considering a Monorepo is “what to do when we try to branch out and work on a feature in a specific project?”

And that is a pretty good question. With Monorepo, all the projects and libraries are tightly coupled in one repository, and it gives us the feeling that working on a specific branch is awkward.

It is true that when we do a checkout to a new branch, we create a copy of the entire repository.

But code being merged back contains only changes we do, so eventually, most of our commits will be atomic.

Monorepo Also Has Disadvantages

Monorepo can help simplify some issues I mentioned earlier, but on the other hand, it can create other problems as well.

The first issue is perhaps the git performance and history. Using a Monorepo means we need to clone all the projects and libraries since they are all in the same repository.

If we have only one or two medium projects, that can be reasonable. But what if we have five or six medium/large projects?

And it doesn’t end just with cloning – what about git pull actions when we have a large team?

When we are in a Monorepo workspace, we pull all the changes from all projects every time, which can be a large amount of data.

Speaking on git, another issue is git history, which is now merged from all projects and libraries.

Another issue Monorepo creates is the inability to restrict access to certain parts of the code.

With Monorepo, all the developers have access to all projects and libraries. Again, when we have a big team, this can be a problem.

The last issue with Monorepo – at the beginning of the book, we discussed the impact of having your architecture modular and what does it mean to keep the SoC (“separation of concerns”).

Using a Monorepo means we are losing the modularity advantages outside the repository.

We cannot share our libraries with projects outside the repository, not to mention making them open source projects.

Solutions to Monorepo Issues

Monorepo is very simple to set up, but as we just saw, it comes with some significant drawbacks, especially when dealing with a big team or many projects.

In the bottom line, like most development issues, it is just a trade-off. And even with Monorepo, we can deal with some of the problems and “pay” with simplicity.

Disassemble Your Monorepo

One option to solve git access, performance, and history is to create several “Monorepos” or a “Libraries Monorepo” (see Figure 6-12).

On the one hand, creating a repository only for packages solves the issues I just mentioned but separates the projects from each other.

On the other hand, it makes it harder to make cross-project changes, which is a significant benefit of one big Monorepo.

Changing a library behavior requires us to test the change in other projects.