Couchy

Welcome to Couchy!

The idea here is to use Carthage to manage multiple Xcode projects. Yes, I am aware that Cocoapods exists, but it comes with limitations. Namely, it's very difficult to create a centralized core for your various white-labels if your core is a mixed-language framework.

Couchy is an attempt at solving this problem by using Carthage's tagging and update system along with the xcodeproj ruby gem to build a setup that allows the developer to have a self-contained, editable "Couchy" core that is used by the two sample white-labels, "UsesCouchy" and "CouchyLite".

Why "Couchy"? Well, it uses CouchbaseLite. Several projects of mine depend on CouchbaseLite; this is fine, as it exists as a cocoapod. However, the cocoapod is written in Objective-C. This itself wouldn't be a problem, but not all headers included are public. This means that if your core is a cocoapod and it also depends on the couchbase cocoapod, then you can't include .swift files in your cocoapod if you intend to use it as a dynamic framework.

So, I've abandoned Cocoapods in favor of using Carthage. You are limited to projects that are Carthage-compatible, which currently seems smaller than the set of projects that are Cocoapods-compatible, but if you too have this problem, it might be worth it to convert to Carthage.

Recommended Flow:

I have two repositories on my system. I recommend making a folder for Couchy itself, and a separate folder for the white-labels (mine is called couchy-suite). Setting up the folder structure this way facilitates getting the 'feel' for development; I might add a new image to the framework itself, and then go ahead and introduce those changes with sh update.sh local.

UsesCouchy and CouchyLite are included to demonstrate that the dependencies used in Couchy can be used in both swift and objective-c projects.

In Action:

After setting up Couchy (and perhaps before diving right into development), try out the sample tags I created! v1.1 introduces a CouchyController that is set as the root for the white-labels. Run both projects and smile when the build succeeds in both an Objective-C and Swift project! Then, you can update to v1.2 to see the CouchyController get a much needed facelift. I've provided this as visual proof, but you can also see that the white-labels successfully compile a mix of objects--couchbaselite items, a swift ParentContainer class, and some objective-c ChildModels. So while updating Couchy itself is a timesink, development on the white-labels doesn't have to be nearly as painful.

To use Couchy:

First, and most importantly, understand that this repository is actually 2 repositories. The aim is to use the couchy branch to edit the core, and then github's tags to handle the "Couchy" core source. That's the first 'repository'. The second one takes the form of gitflow (ideally). As a quick overview, you have a master branch with stable releases, and a develop branch that houses, well, developing changes. To work on a feature, use feature/myFeature. Every branch that is a part of gitflow contains all white-labels.

[Note: Considering allowing a couchy/gitflow to better manage the core.]

Second, understand the workflow:

Edit Couchy.xcodeproj in the source folder, and commit on a couchy branch. Make sure you push the specific tag as well (See info on tagging in Github).
Run the update script.
1. Make sure permissions are enabled. If you can't run it, try chmod+x update.sh in the correct directory.
2. I run a zsh shell, so the easiest thing for me to do is sh update.sh to run the script.
3. Syntax: update.sh <remote|local>
  - Basic local update: sh update.sh or sh update.sh local (uses v1.1 tag)
  - Basic remote updae: sh update.sh remote (still uses v1.1 tag)
  - Specific update: sh update local v1.4
Use the updates. I currently use carthage update Couchy --platform iOS as the update command, but this would change if you have multiple platforms (like WatchOS or tvOS).

[Note: Need to add functionality in update script to include multiple targets.]

If you visit commits b0499daa and 0705c85, you can see an example of starting switching Couchy versions. The only action taken in these two commits were sh update.sh remote and sh update.sh remote v1.2, respectively.

Warnings and Known Issues:

It's really slow. I currently want to be able to just build Couchy without updating the dependencies, but I haven't figured out a way to do so. This means that right now, if you're doing framework dev alongside app creation, you can get stuck waiting for 5+ minutes just trying to integrate framework changes.
This has more to do with Carthage, so those already familiar can skip this part. Carthage expects semantic versioning, which means you version your projects like so: a.b.c where a is a major relase, b is a minor one, and c is a patch. Furthermore, your version can't have letters in it like this: 1.2.alpha-1. So if your project doesn't follow this scheme, it's time to conform.
Another Carthage-specific issue: Because Carthage uses the tagging system, take time to refresh yourself on git's method of tagging. Tags point to commits, so when you force-push to overwite one or several commits, things can get hairy. I personally like to overwrite my tags sometimes (not the best practice, mind you), so I've included a line in upd.sh that clears the cache and enables Carthage to update an overwritten tag. I don't think just clearing the cache on update is necessarily, hence the warning/issue.

⚠️ Final Note: This is just a work in progress. The script is likely to work fine, but always be careful running shell scripts. Also, I'm still working out kinks, so as mentioned, carthage updates are very slow. And because FRAMEWORKS are being copied over, git pushes can be slow too.

Enjoy!

ravenesque1 / Couchy