Rewrite contributing guide

CONTRIBUTING.md

@@ -1,24 +1,41 @@
 # Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/piknotech/SFSafeSymbols. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-## Getting Started
+Bug reports and suggestions for improvements are welcome! For this, please [raise an issue on GitHub](https://github.com/piknotech/SFSafeSymbols/issues). [Pull requests](https://github.com/piknotech/SFSafeSymbols/pulls) are also very much welcome. However, for non-trivial changes, please make sure to raise an issue before opening up a PR that addresses the issue.
 
-To get started contributing, just open the existing Xcode project and you're ready to go!
+## Core Contributors
 
-### Commit Messages
+There's a **team of core contributors** responsible for the management of this repository, i. e. configuring the CI, releasing new versions and **managing PRs & issues**. Everyone that created at least one non-trivial PR (i. e. not just correcting spelling mistakes) can **request to become a core contributor** once the PR has been approved and merged. 
 
-Please try to follow the same syntax and semantic in your **commit messages** (see rationale [here](http://chris.beams.io/posts/git-commit/)).
+## Pull Requests
 
-### Tracking Changes
+When issuing a pull request, please **add a summary of your changes to the `CHANGELOG.md` file** and credit yourself as the author.
 
-When issuing a pull request, please add a summary of your changes to the `CHANGELOG.md` file and credit yourself as the author.
+The **approval of a core contributor** is required before merging a PR. When a core contributor creates a PR themselves and no other core contributor responds in a week's time, they are allowed to **merge the PR themselves** even without further approval. All changes (apart from trivial changes, i. e. when releasing a new version) **must be made via PRs**.
 
-## Releasing
+## Git
 
-To release a new version, do the following things:
+Please write **meaningful commit messages** (see rationale [here](http://chris.beams.io/posts/git-commit/)).
 
-1. Bump the build num in the `SFSafeSymbols.podspec` and at all places in the `README.md` (Version Badge, Version Badge Alt Text, Installation Instructions).
-2. Update the `CHANGELOG.md` file by changing the *Unreleased* title to the version num and the release date. Then add a new *Unreleased* Section on top, maintaining the 3 existing subsections (Added, Changed, Fixed).
-3. Release on GitHub and copy the changelog contents for this version into the release notes on GitHub.
-4. Publish on CocoaPods using `pod trunk push SFSafeSymbols.podspec --allow-warnings`.
+## Updating to a new SF Symbols version
+
+With the current structure of the repository, where **most code is generated** by the `SymbolsGenerator` helper tool, it is quite easy to update `SFSafeSymbols` to a new SF Symbols version (as long as there are no breaking changes in the way Apple organizes the symbols):
+
+1. **Update the files** in the `/SymbolsGenerator/Sources/SymbolsGenerator` folder to the latest SF Symbols version. Some of the files are created manually (there's a comment at the top of these files, explaing how it is done), some other files are copied from the *Package Contents* of the SF Symbols app.
+2. Open a terminal and change to the root folder of the repository. **Then run `make generate-symbol`**.
+3. If new files are created by the generator tool (which is expected to happen when updating to a new SF Symbols version), make sure they are **added to the `SFSafeSymbols.xcodeproj`**.
+4. **Update the `README.md`**, so that support for the new SF Symbols version is mentioned there.
+5. **Check the CI configuration** and, if needed, make adjustments (or ask a core contributor to do so), so that the new changes are properly tested with a matching Xcode version.
+
+## Releasing a new version
+
+To be able to release a new version, you **need to be a core contributor**, i. e. have write access to the repository and CocoaPods. If you have these privileges, it's up to you to release a new version whenever you feel that it's appropriate.
+
+To release a new version, follow these steps:
+
+1. **Bump the build num** in the `SFSafeSymbols.podspec` and at all places in the `README.md` (Version Badge, Version Badge Alt Text, Installation Instructions).
+2. **Update the `CHANGELOG.md` file** by changing the *Unreleased* title to the version num and the release date. Then add a new *Unreleased* Section on top, keeping the 3 existing subsections (Added, Changed, Fixed).
+3. **Commit these changes directly to the `stable` branch** with the commit message `Bump version num & update changelog`.
+4. **Release on GitHub** and copy the changelog contents for this version into the release notes on GitHub.
+5. **Publish on CocoaPods** using `pod trunk push SFSafeSymbols.podspec --allow-warnings`.

README.md

@@ -47,13 +47,12 @@
 
 `SFSafeSymbols` supports multiple SF Symbols versions at the same time by utilizing the `@availability` flag. The following versions are currently supported:
 
-- SF Symbols 1.0 (`@available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *)`)
-- SF Symbols 2.0 (`@available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)`)
-- SF Symbols 2.1 (`@available(iOS 14.2, macOS 11.0, tvOS 14.2, watchOS 7.1, *)`)
-- SF Symbols 2.2 (`@available(iOS 14.5, macOS 11.3, tvOS 14.5, watchOS 7.4, *)`)
-- SF Symbols 3.0 (`@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)`)
-- SF Symbols 3.1 (`@available(iOS 15.1, macOS 12.0, tvOS 15.1, watchOS 8.1, *)`)
-
+- SF Symbols 1.0 (iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0)
+- SF Symbols 2.0 (iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0)
+- SF Symbols 2.1 (iOS 14.2, macOS 11.0, tvOS 14.2, watchOS 7.1)
+- SF Symbols 2.2 (iOS 14.5, macOS 11.3, tvOS 14.5, watchOS 7.4)
+- SF Symbols 3.0 (iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0)
+- SF Symbols 3.1 (iOS 15.1, macOS 12.0, tvOS 15.1, watchOS 8.1)
 
 ## Motivation
 
@@ -65,6 +64,8 @@ UIImage(systemName: "circle.fill")
 
 It didn't take long until [first ideas came up](https://twitter.com/simjp/status/1135642837322588161?s=12) to make these icons accessible in a safe way using a framework. And this is just what `SFSafeSymbols` does!
 
+Additionally, every symbol is documented in code so that lookups in the SF Symbols app (e. g. about available layersets, available localizations & the look of the symbol) are no longer needed.
+
 ## Installation
 
 `SFSafeSymbols` can be installed via the **Swift Package Manager (recommended)**, Carthage or CocoaPods.