Skip to content

Commit 87da822

Browse files
paulb777paulb777
authored
Zip docs organization (#7202)
1 parent 651402c commit 87da822

File tree

3 files changed

+112
-95
lines changed

3 files changed

+112
-95
lines changed

‎ReleaseTooling/DEVELOP.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Firebase Release Tools
2+
3+
This project includes Firebase release tooling including a zip builder and a
4+
Firebase release candidate creation tool.
5+
6+
The tools are designed to fail fast with an explanation of what went wrong, so
7+
you can fix issues or dig in without having to dig too deep into the code.
8+
9+
## Zip Builder
10+
11+
For general usage, see [README.md](README.md).
12+
13+
### Firebase Release zip building
14+
15+
If the `--zip-pods` option is not specified, the tool will build a Firebase zip distribution.
16+
17+
For release engineers (Googlers packaging an upcoming Firebase release) these commands should also
18+
be used:
19+
- `--custom-spec-repos sso://cpdc-internal/firebase`
20+
- This pulls the latest podspecs from the CocoaPods staging area.
21+
- `--enable-carthage-build` Turns on generation of Carthage zips and json file updates.
22+
- `--keep-build-artifacts` Useful for debugging and verifying the zip build contents.
23+
24+
Putting them all together, here's a common command to build a releaseable Zip file:
25+
26+
```
27+
swift run zip-builder --update-pod-repo \
28+
--custom-spec-repos sso://cpdc-internal/firebase \
29+
--enable-carthage-build \
30+
--keep-build-artifacts
31+
```
32+
33+
#### Carthage
34+
35+
Carthage binaries can also be built at the same time as the zip file by passing in `--enable-carthage-build`
36+
as a command line argument. This directory should contain JSON files describing versions and download
37+
locations for each product. This will result in a folder called "carthage" at the root where the zip directory exists
38+
containing all the zip files and JSON files necessary for distribution.
39+
40+
## Firebase Releaser
41+
42+
Provides several functions for staging a Firebase release candidate. See the internal go/firi link
43+
for the process documentation.
44+
45+
### Launch Arguments
46+
47+
See `main.swift` for information on specific launch arguments.
48+
49+
You can pass in launch arguments with Xcode by selecting the "firebase-releaser" scheme
50+
beside the Run/Stop buttons, clicking "Edit Scheme" and adding them in the "Arguments Passed On Launch"
51+
section.
52+
53+
## Development Philosophy
54+
55+
The following section describes the priorities taken while building this tool and should be followed
56+
for any modifications.
57+
58+
### Readable and Maintainable
59+
This code will rarely be modified outside of bug fixes, but read very frequently. There should be no
60+
"magic lines" that do multiple things. Verbosity is preferred over making the code shorter and
61+
performing multiple actions at once. All functions should be well documented.
62+
63+
### Avoid Calling bash Commands Where Possible
64+
Instead of using `cat`, `find`, `grep`, or `perl` use `String` APIs to read the contents of a file,
65+
`FileManager` to properly list contents of a directory, `RegularExpression` for pattern matching,
66+
etc. If there's a `Foundation` API available, it should be used.
67+
68+
### Understandable Output
69+
The output of the script should make it immediately obvious if there were any issues and exactly
70+
what those issues were, without looking at the code. It should also be very clear if the Zip file
71+
was properly built and output the file location.
72+
73+
### Show Xcode and API Output on Failures
74+
In the event that there's an Xcode build failure, the logs should be surfaced immediately to aid
75+
debugging. Release engineers should not have to find the Xcode project manually. That being said, a
76+
link to the Xcode project file should be logged as well in case it's necessary. Same goes for errors
77+
logged by exceptions (ex: `FileManager`).
78+
79+
### Testable and Debuggable
80+
Components and functions should be split up in a way that make them easy to test and easy to debug.
81+
Prefer small functions that have proper failure conditions and input validated with `guard`
82+
statements, throwing `fatalError` with a well written error message if it's a critical issue that
83+
prevents the Zip file from being built properly.
84+
85+
### Works from the Command Line or Xcode (Environment Agnostic)
86+
The script should be able to run from the command line to allow for easier automation and Xcode for
87+
simpler debugging and maintenance.
88+
89+
### Any Failure Exits Immediately
90+
The script should not continue if anything necessary for a successful Zip file fails. This includes
91+
things like compiling storyboards, moving resources, missing files, etc. This is to ensure the
92+
integrity of the zip file and that any issues during testing are SDK bugs and not related to the
93+
files and folders.
94+
95+
### Prefer File `URL`s over Strings
96+
Instead of relying on `String`s to represent file paths, use `URL`s as soon as possible to avoid any
97+
missed or double slashes along with other issues.

‎ReleaseTooling/README.md

Lines changed: 10 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,14 @@
33
This project includes Firebase release tooling including a zip builder and a
44
Firebase release candidate creation tool.
55

6-
The tools are designed to fail fast with an explanation of what went wrong, so
7-
you can fix issues or dig in without having to dig too deep into the code.
6+
The rest of this file documents using the `zip-builder` tool. Information about the rest of the
7+
tools for managing Firebase releases and information about developing these tools is at
8+
[DEVELOP.md](DEVELOP.md)
89

910
## Zip Builder
1011

11-
This is a Swift Package Manager project that allows users to package an iOS Zip file of binary
12-
packages.
12+
The `zip-builder` tool generates a zip distribution of binary `.xcframeworks` from an input set of
13+
CocoaPods.
1314

1415
### Requirements
1516

@@ -59,93 +60,11 @@ Indicates to install the version 3.2.0 of "GoogleDataTransport" and the latest
5960
version of "FirebaseMessaging". The version string is optional and can be any
6061
valid [CocoaPods Podfile version specifier](https://guides.cocoapods.org/syntax/podfile.html#pod).
6162

62-
6363
Optional common arguments:
6464
- `--no-update-pod-repo`
6565
- This is for speedups when `pod repo update` has already been run recently.
66-
67-
### Firebase Release zip building
68-
69-
If the `--zip-pods` option is not specified, the tool will build a Firebase zip distribution.
70-
71-
For release engineers (Googlers packaging an upcoming Firebase release) these commands should also
72-
be used:
73-
- `--custom-spec-repos sso://cpdc-internal/firebase`
74-
- This pulls the latest podspecs from the CocoaPods staging area.
75-
- `--enable-carthage-build` Turns on generation of Carthage zips and json file updates.
76-
- `--keep-build-artifacts` Useful for debugging and verifying the zip build contents.
77-
78-
Putting them all together, here's a common command to build a releaseable Zip file:
79-
80-
```
81-
swift run zip-builder --update-pod-repo \
82-
--custom-spec-repos sso://cpdc-internal/firebase \
83-
--enable-carthage-build \
84-
--keep-build-artifacts
85-
```
86-
87-
#### Carthage
88-
89-
Carthage binaries can also be built at the same time as the zip file by passing in `--enable-carthage-build`
90-
as a command line argument. This directory should contain JSON files describing versions and download
91-
locations for each product. This will result in a folder called "carthage" at the root where the zip directory exists
92-
containing all the zip files and JSON files necessary for distribution.
93-
94-
## Firebase Releaser
95-
96-
Provides several functions for staging a Firebase release candidate. See the internal go/firi link
97-
for the process documentation.
98-
99-
### Launch Arguments
100-
101-
See `main.swift` for information on specific launch arguments.
102-
103-
You can pass in launch arguments with Xcode by selecting the "firebase-releaser" scheme
104-
beside the Run/Stop buttons, clicking "Edit Scheme" and adding them in the "Arguments Passed On Launch"
105-
section.
106-
107-
## Development Philosophy
108-
109-
The following section describes the priorities taken while building this tool and should be followed
110-
for any modifications.
111-
112-
### Readable and Maintainable
113-
This code will rarely be modified outside of bug fixes, but read very frequently. There should be no
114-
"magic lines" that do multiple things. Verbosity is preferred over making the code shorter and
115-
performing multiple actions at once. All functions should be well documented.
116-
117-
### Avoid Calling bash Commands Where Possible
118-
Instead of using `cat`, `find`, `grep`, or `perl` use `String` APIs to read the contents of a file,
119-
`FileManager` to properly list contents of a directory, `RegularExpression` for pattern matching,
120-
etc. If there's a `Foundation` API available, it should be used.
121-
122-
### Understandable Output
123-
The output of the script should make it immediately obvious if there were any issues and exactly
124-
what those issues were, without looking at the code. It should also be very clear if the Zip file
125-
was properly built and output the file location.
126-
127-
### Show Xcode and API Output on Failures
128-
In the event that there's an Xcode build failure, the logs should be surfaced immediately to aid
129-
debugging. Release engineers should not have to find the Xcode project manually. That being said, a
130-
link to the Xcode project file should be logged as well in case it's necessary. Same goes for errors
131-
logged by exceptions (ex: `FileManager`).
132-
133-
### Testable and Debuggable
134-
Components and functions should be split up in a way that make them easy to test and easy to debug.
135-
Prefer small functions that have proper failure conditions and input validated with `guard`
136-
statements, throwing `fatalError` with a well written error message if it's a critical issue that
137-
prevents the Zip file from being built properly.
138-
139-
### Works from the Command Line or Xcode (Environment Agnostic)
140-
The script should be able to run from the command line to allow for easier automation and Xcode for
141-
simpler debugging and maintenance.
142-
143-
### Any Failure Exits Immediately
144-
The script should not continue if anything necessary for a successful Zip file fails. This includes
145-
things like compiling storyboards, moving resources, missing files, etc. This is to ensure the
146-
integrity of the zip file and that any issues during testing are SDK bugs and not related to the
147-
files and folders.
148-
149-
### Prefer File `URL`s over Strings
150-
Instead of relying on `String`s to represent file paths, use `URL`s as soon as possible to avoid any
151-
missed or double slashes along with other issues.
66+
- `--minimum-ios-version <minimum-ios-version>`
67+
- Change the minimimum iOS version from the default of 10.
68+
- `--output-dir <output-dir>`
69+
- The directory to copy the built Zip file to. If this is not set, the path to the Zip file will
70+
be logged to the console.

‎ReleaseTooling/Sources/ZipBuilder/main.swift

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ struct ZipBuilderTool: ParsableCommand {
9393
/// Custom CocoaPods spec repos to be used.
9494
@Option(parsing: .upToNextOption,
9595
help: ArgumentHelp("""
96-
A list of custom CocoaPod Spec repos. If not provided, the tool will only use the \
96+
A list of private CocoaPod Spec repos. If not provided, the tool will only use the \
9797
CocoaPods master repo.
9898
"""))
9999
var customSpecRepos: [URL]
@@ -102,14 +102,15 @@ struct ZipBuilderTool: ParsableCommand {
102102

103103
/// The minimum iOS Version to build for.
104104
@Option(default: "10.0",
105-
help: ArgumentHelp("The minimum supported iOS version. The default is 10.0."))
105+
help: ArgumentHelp("The minimum supported iOS version."))
106106
var minimumIOSVersion: String
107107

108108
/// The list of architectures to build for.
109109
@Option(parsing: .upToNextOption,
110110
help: ArgumentHelp("""
111-
The list of platforms to build for. The default list is \
112-
\(TargetPlatform.allCases.map { $0.sdkName }).
111+
The list of target platforms to build for. The default list is \
112+
\(TargetPlatform.allCases.map { $0.sdkName }). Note that `macosx` is currently Catalyst \
113+
only.
113114
"""))
114115
var platforms: [TargetPlatform]
115116

0 commit comments

Comments
 (0)