Skip to content

Latest commit

 

History

History
144 lines (94 loc) · 9.29 KB

CONTRIBUTING.md

File metadata and controls

144 lines (94 loc) · 9.29 KB

Contributing to mistica-ios

Thank you for your interest in Mística. You can contribute to this project in several ways:

Feel free to contact maintainers at the Mística Teams Channel. Don't hesitate to ask any questions and share your ideas

Pull Requests

We would love to accept your Pull Requests but please, before starting your development, create an issue.

When selecting the reviewers for your pull request, use the Telefonica/iOS team as it will automatically select two reviewers from the team.

Pull request will be merged by the repo owners by squashing all commits and combining them into one that will have a meaningful message following the "Commit messages" guidelines.

Release workflow

To create a new release, use the GitHub action Release. The process is automated using semantic-release, which will increase version numbers, update the CHANGELOG.md and create a new GitHub release.

Commit messages

semantic-release uses the uses Angular Commit Message Conventions to determine the type release to generate. The following list includes some examples of commit messages and the type of release that will be created:

Commit message Release type
fix(Button): make it green again in MovistarES Patch Release
feat(Button): added a new fancy animation Minor Release
feat(FontStyle): update font styles

BREAKING CHANGE: The existing font style has changed.
Major Release

In order for a feature/fix to be considered a major release, it needs to include the BREAKING CHANGE: body in the commit message. Refer the the full list of commit message types here.

To revert a commit, the commit message should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>, where the hash is the SHA of the commit being reverted. semantic-release will automatically skip the original and the revert commit from the CHANGELOG.md if the release has not been yet created, if not, it will create a new one.

revert: fix(Button): make it green again in MovistarES

This reverts commit c3cdc70e88dc0bf9de849fb21c6b4ddf22b27470

SwiftFormat

When a pull request is created, swiftformat runs automatically over the commits in that branch and formats the code according to the rules defined in the .swiftformat file. The formated changes will be commited and added to the pull request automatically.

SwiftFormat is located as a precompiled binary in scripts/swiftformat. In order to update the library, follow the instructions to check out and build SwiftFormat manually on macOS from https://github.com/nicklockwood/SwiftFormat#command-line-tool. The binary resulting after building the tool for release, by default located under the .build/release folder, can directly replace the binary in Mistica in the scripts folder.

Bug reports

If something is broken or not working as expected, let us know!

🐛 Open a Bug issue

Feature requests (no UI/UX changes)

If you need additional functionality, support a new use case, improve a component API...

🚧 Open a Feature Request issue

Important: Your feature request should not include UI or UX changes, only implementation details, because those kind of changes must be evaluated, approved and documented by the Design Core Team (see New component proposals or UI/UX changes section).

Documentation and help requests

Is something in our documentation not well explained? Do you need help using a component?

📘 Open an Documentation issue

New component proposals or UI/UX changes

Adding a new component to the Mística Design System or updating the UI/UX of an existing one requires to follow a process where the component and its use cases will be evaluated by the Design Core Team.

Share your ideas at the Mística Teams Channel or open an issue in the main Mistica Repository

How to work with mistica-ios

To create or modify components from the Mistica library follow the next steps:

  1. Clone this repo
  2. Open Package.swift
  3. Place the new component under the Components folder. The component should have a proper definition by the design team.
  4. Add a new entry to MisticaCatalog showing how the new component works and documentation with component details and usage.

When implementing the component, try to have in mind the following guidelines:

  • The component should be implemented to be reusable. Make it generic enough so that other teams can also use it.
  • Make sure the component reiszes correctly (we support iPad multitasking, so any screen can resize at any given time).
  • Don't forget accessibility (VoiceOver, Dynamic Type...).
  • Pay attention to user interaction (Gestures, Haptics, 3D Touch...)
  • Although this should be transparent to you, take into account multiple brands.
  • To help other developers, add documentation about the new component.

Skins

Mistica brands are based on tokens. Those tokens define the brand customization like font weights, sizes, colors, etc. In order to automatise this, we can execute this GitHub action to generate those tokens based on the mistica-design specification. You can also execute it manually using the actions defined in the Makefile. Example:

make skin

Testing

Running Tests

To run tests, ensure you have the appropriate simulator defined in the MakeFile. Open Mistica.xcodeproj after following the How to work with mistica-ios guide and click any Test button.

Creating a Test

  • Open Mistica.xcodeproj and create a new file in MisticaTest folder.
  • Select the generic template Unit Test Case Class.
  • Name the class, keep the XCTestCase as super class and select Swift if needed.
  • Select the appropriate test target

We use Screenshot or Snapshot type tests using a library named SnapshotTesting, so please go the library repository and read the documentation.

Snapshot testing with Apple Silicon processors

There are some slight differences in snapshots depending on whether they were generated by an Intel processor or Apple Silicon processor that cause the tests to fail (See more info here). In order to avoid using perceptualPrecision where we could have false tests passing, we should execute/record the tests using a Rosetta simulator:

Rosetta simulator in XCode

To check if everything is configured properly, try to execute the tests in main where all of them should pass.

Record new Snapshot testing reference screenshots for a PR

You can directly generate new reference screenshots using a Github Action in a pull request. That way you can avoid having to generate them in your development Mac and the possible problems. To do it, you just need to add a comment to the PR with the text /record-screenshots and the Github Action will generate new screenshots, commit them to the PR branch, execute the tests again and update the commit status with the test results.