Skip to content

Latest commit

 

History

History
191 lines (139 loc) · 7 KB

CONTRIBUTING.md

File metadata and controls

191 lines (139 loc) · 7 KB
Raw

Contributing to CoatySwift

Contributions to the CoatySwift framework are welcome and appreciated. If you wish to contribute please follow the guidelines described in this document.

Table of Contents

Workflow

Contributions should be incorporated into the repository using pull requests on a separate branch. We use the GitHub Pull Request Workflow. The mentioned link is the recommended documentation to read and understand this workflow.

Our Git development workflow includes the following steps as described here.

Git Commit Style

We are using the Conventional Commits Style for our commit messages:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Conventional Commits Style helps structuring Git commit messages in a way that allows automatic generation of changelogs. These conventions can form the basis for automatic version bumping and CHANGELOG management when cutting a new release.

Note: The current build process does not support automatic versioning and changelog management. However, it is intended to add this feature in a future release.

License and Copyright Notice

CoatySwift source code is licensed under the MIT License. Attach a license and copyright notice to the top of each created source files as follows:

// Copyright (c) <year> <contributor>. Licensed under the MIT License.

<year> specifies the year of first publication and must not be changed when you modify the contents of the file later on. Do not add additional copyright notices or dates when the work is revised at a future time.

Contributions without this header on each new source file won't be accepted.

The meaning of source file covers all files, which allow adding a comment easily (e.g. .swift) and contribute to the core value of the project by adding originality (e.g. no configuration files).

Documentation and media work (such as icons) should be licensed under a Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).

Coding Style

The framework includes a custom SwiftLint configuration that can also be used in Coaty application projects.

Build CoatySwift

You need XCode 11.0 or higher (needed for Swift Package Manager).

To build and run the CoatySwiftExample application including the CoatySwift framework, open the Example/Example.xcodeproj in the CoatySwift root folder and press Run.

Develop CoatySwift using XCode

After cloning the repository onto your local machine, open the root using XCode. Wait for XCode to fetch all of the dependencies. Perform the development changes in the CoatySwift target. After rebuilding the package, changes should be visible in e.g. Example project.

Autocompletion should work in the new/modified files now. If this is not the case try: 1) cleaning the build folder 2) relaunching XCode. In case those steps do not solve the problem try removing /DerivedData directory from your local XCode configuration (instructions can be found on the internet).

Generate CoatySwift documentation

The framework API documentation can automatically be generated by using Jazzy. From the root directory of the repository run:

jazzy

Execute the command to generate HTML documentation from the Swift source code and the included comments. The generated documentation is written to the docs/api/ folder and accessible by opening a web browser on the index.html file. The Jazzy configuration is located in the .jazzy.yaml file in the repository root.

Test CoatySwift

To test the CoatySwift framework using included Unit Tests, clone the project and open it's root folder using XCode. Wait for it to fetch all of the required dependencies. Then select Test Navigator Tab in Navigator View, enable required tests and run them. Results can be seen in the Report Navigator tab.

Release CoatySwift

Before releasing a new CoatySwift version, ensure to test the framework code against the example in the Example/Example.xcodeproj of the CoatySwift repo and the examples in the swift sections of the coaty-examples repo on GitHub. Also follow the guide on how to test the framework (see above) and ensure that all tests pass successfully.

You can also use pod lib lint to validate the Pod locally using the files in the CoatySwift working directory (only for CocoaPods).

CocoaPods

In order to release a new CoatySwift version on CocoaPods, you have to follow these steps:

  1. Update the pod version in the CoatySwift.podspec file located in the repository root. Follow semantic versioning.

  2. Generate Coaty framework documentation. First, update the module_version in the .jazzy.yaml file to match the version number from step 1.

    jazzy

  3. Manually update CHANGELOG.md with release information from the conventional commits. Take a look at the Coaty JS CHANGELOG to see how the format should look like.

  4. Commit with message chore(release): v[pod version] and push all your changes to the develop branch.

  5. Create an annotated git tag for the new pod version and push it. Make sure that [pod version] matches the version number from step 1.

    git tag -a -f -m 'chore(release): v[pod version]' [pod version]
git push origin --tags

  6. Merge the local develop branch into local master and push master. This ensures GitHub Pages automatically regenerates the CoatySwift documentation website.

  7. You now need to check whether the pod passes verification. Run the following command:

    pod spec lint CoatySwift.podspec

  8. If the previous step was successful, deploy the new Podspec to make it publicly available:

    pod trunk push CoatySwift.podspec

    This step assumes that you have already registered an account on CocoaPods Trunk and have been added as a library owner for the CoatySwift pod.

Swift Package Manager

Swift Package Manager does not require a manual release process. As soon as the newest version has been pushed to the repository, it can be used by anyone.

Copyright (c) 2019 Siemens AG. This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.