Merge pull request #71 from veracode/develop

Gen IR version: 0.5.0

.github/workflows/SwiftLint.yml

@@ -0,0 +1,17 @@
+name: SwiftLint
+
+on:
+  pull_request:
+    paths:
+      - '**.swift'
+
+jobs:
+  # Runs swiftlint on any pull request to main (note: this runs for _all_ files, not only the changed files in the PR!)
+  SwiftLint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cirruslabs/swiftlint-action@v1
+        with:
+          version: latest
+          args: "--strict"

.github/workflows/build.yml

@@ -7,14 +7,11 @@ on:
 
 jobs:
   build:
-    runs-on: macos-12
-    # This doesn't seem to work, even when the internet seems to indicate it should...
-    env:
-      DEVELOPER_DIR: /Applications/Xcode_14.2.app/Contents/Developer
+    runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: 🔨 Build
         run: |
-          sudo xcode-select -s /Applications/Xcode_14.2.app/
+          sudo xcode-select -s /Applications/Xcode_15.4.app/
           swift build

.gitignore

@@ -16,4 +16,5 @@ output/
 *.xcarchive/
 *.bc
 *.dia
-_build/
+_build/
+**/.build/

.swiftlint.yml

@@ -1,10 +1,25 @@
 excluded:
-  - .build/
   - .swiftpm/
   - .vscode/
-  - PBXProjParser/.build/ # https://github.com/realm/SwiftLint/issues/2329 doesn't support recursive globs yet
-  - GenIRLogging/.build/
+  - "**/.build/*"
+  - .build/
+  - TestAssets/
+  - PIF/.build/
+  - '**/Package.swift'
+  - Package.swift
+  - PIF/Sources/pif-parser/pif-parser.swift
+
+disabled_rules:
+  - todo
+  - nesting
 
 line_length:
-  warning: 150
+  warning: 200
   ignores_comments: true
+
+missing_docs:
+  warning:
+    - public
+
+opt_in_rules:
+  - missing_docs

Documentation/branching_model.md

@@ -0,0 +1,31 @@
+# Gen IR Branching Model
+
+![Branching Model](images/branching_model.svg)
+
+Gen IR uses the [GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) branching model. This model is tried, tested, and has remained so over 10+ years for a project of this type.
+
+Modifications to the model:
+
+- No `hotfix` branch for now. We can just follow the regular release flow
+- Unstable releases are tagged on `develop`
+  - These should be set as `prelease` in the GitHub Release!
+
+## Versioning
+
+We use the [SemVar 2.0.0](https://semvar.org) versioning scheme.
+
+Releases should increment this (see [Releasing an Update](releasing_an_update.md))
+
+## New Feature Development
+
+- Create a new branch off `develop` and name it appropriately
+  - `git checkout develop && git pull && git checkout -b sensibly_named_branch`
+- Add your new feature commits
+- Create a merge request to the `develop` branch
+
+## New Release
+
+- Create a branch off `develop` and name it `release/<version>`
+- Test, QA, fix
+- Merge to `main` and create a release
+- Merge to `develop`, remove the `develop` tag and retag the new commit with `develop`

Documentation/releasing_an_update.md

@@ -3,34 +3,96 @@
 When you have an update for `gen-ir`, there's a couple things that need to happen:
 
 - Release a version in the `gen-ir` repo
-- Update the version in the `homebrew-tap` repo, so brew picks up the update
+- Update the version(s) in the `homebrew-tap` repo, so brew picks up the update(s)
 
-## Releasing a gen-ir version
+## Releasing a Gen IR version
 
-To release a new version of `gen-ir`, create a Pull Request with your changes, ensuring the `build` pipeline finishes successfully, then attach one of the following labels to the PR.
+As mentioned in the [Branching Model](branching_model.md), features should be merged into the `develop` branch. You should never merge a feature directly to `main`.
 
-- `merge-bump-major`
-  - This will merge the PR & bump a major version (i.e. 1.0.0 to 2.0.0)
-- `merge-bump-minor`
-  - This will merge the PR & bump a minor version (i.e. 1.0.0 to 1.1.0)
-- `merge-bump-patch`
-  - This will merge the PR & bump a patch version (i.e. 1.0.0 to 1.0.1)
-- `merge-no-bump`
-  - This will merge the PR with no version bump
+To release a new version of `gen-ir`, create a release branch and open a merge request from the release branch (see the [Branching Model](branching_model.md)) to `main` at the commit point you're wanting to release and to `develop`. Allow any automated check, peer reviews, and - when approved - merge the request.
 
-This will merge the PR, bump the version, fix the version in the `Versions.swift` file, push the commit to main, tag the _new_ commit with the version number, and perform a GitHub release with that tag.
+Then, on your local machine:
 
-Now, navigate to the release and note the tag name & revision for the next part
+- Change to `main` and pull the changes
+  - `git checkout main && git pull`
+- Create the new tag for the release:
+  - `git tag -a 1.0.0 -m "Gen IR version: 1.0.0`
+  - `git push --tags`
+- Change to `develop` and pull the changes
+  - `git checkout develop && git pull`
+- Recreate the new `develop` tag for the release:
+  - `git tag -d develop && git push --delete origin develop`
+  - `git tag -a develop -m "Gen IR Develop version: <commit hash>`
+  - `git push --tags`
 
-## Updating Homebrew Tap
+Then, in the GitHub UI:
 
-The formula for the tap lives in the [veracode/homebrew-taps](https://github.com/veracode/homebrew-tap) repo. This needs to be updated in order to propagate a new version to users.
+- Go to the [Releases](https://github.com/veracode/gen-ir/releases) page
+- Click `Draft a new release`
+- Set the title to the version name
+- From the drop down list, choose your newly created tag
+- Click the `Generate release notes` button to create a change log
+- Ensure `Set as the latest release` is checked
+- Click the `Publish` button
 
-- Create a new branch: `gen_ir_<version>`
-- Update the `gen-ir` formulae url.tag & url.revision keys to match the release the previous step made
-- Open a PR with these changes _and these changes only!_.
-  - If any other changes are detected, or more than one commit is made, homebrew's automation will fail
-- When checks pass, add the `pr-pull` label to the PR
-- Automation will make a new release
+- Click `Draft a new release`
+- Set the title to `develop`
+- From the drop down list, choose your newly created `develop` tag
+- Click the `Generate release notes` button to create a change log
+- Ensure `Set as pre-release` is checked
+- Click the `Publish` button
 
-Users can now run `brew update && brew upgrade` to update `gen-ir` and `brew install gen-ir` will install the latest version.
+A release has been made, congratulations. However there's additional steps for distributing the release via `brew`.
+
+## Distributing a release
+
+Gen IR uses a Homebrew Tap for distribution. In order for the Tap to see the new release, you need to update the [Gen IR Formula](https://github.com/veracode/homebrew-tap/blob/main/Formula/gen-ir.rb).
+
+> Note: You may have to update more than one formula! If you're releasing a new major or minor version, you'll need to ensure versioning of the formula is correct. See the section [Versioning Tap Releases](#versioning-tap-releases) for more information.
+
+First, if you haven't already, checkout the `veracode/homebrew-tap` repo:
+
+```shell
+git clone [email protected]:veracode/homebrew-tap.git
+```
+
+Then, do the following to increment the formula:
+
+- Create a new branch - replacing `<version>` with the released version:
+  - `git checkout -b gen_ir_<version>`
+- Update the `gen-ir.rb` formula:
+  - Change `url.tag`'s value to the tag's name
+  - Change `url.revision` to the commit hash pointed to by the tag
+- Open a merge request with _only these changes!_
+  - If you have more than one commit, or change more than this single file - homebrews automation will refuse to merge the request.
+- When the `test-bot` check passes, add the `pr-pull` label to the request
+- Automation will make the new release
+
+Users can now run `brew update && brew upgrade gen-ir` to update to the latest version.
+
+## Versioning Tap Releases
+
+It is likely that you will need to do One More Thing, which is to ensure the formula is versioned correctly.
+
+Gen IR has the following policy on versions:
+
+- Gen IR will maintain formulae for one version behind _and_ any current prerelease versions
+- Any versioned formulae **must** use `keg_only :versioned_formula`
+  - This means brew will _only_ install into the Cellar, and will not link into the brew prefix
+- Gen IR _will not_ maintain formulae for patch versions
+
+So, if you have released a new major or minor version you should:
+
+- Create a new versioned formula for the previous release to yours
+- Remove any now-deprecated formula(e)
+
+### Creating Versioned Formulae
+
+Using the history of the `homebrew-tap` find the version of the Gen IR formula you're looking for, then copy the file to the `Formula` folder renaming it like so: `gen-ir@<version>`
+
+Edit the file to:
+
+- change the name of the class to add the version, for example version 0.3.11 becomes: `GenIrAT0311`.
+- add the `keg_only :versioned_formula` tag after the `bottle`.
+
+> Note: it is a good idea to run `brew style Formulae/gen-ir@<version>.rb` before you push the commit! Brew is _very_ particular about the layout of a formula and the test-bot will fail if your key isn't in the right spot.