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
- Bug reports
- Feature requests (no UI/UX changes)
- Documentation and help requests
- New component proposals or UI/UX changes
- How to work with mistica-ios
- Skins
- Testing
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.
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.
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 stylesBREAKING 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
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.
If something is broken or not working as expected, let us know!
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).
Is something in our documentation not well explained? Do you need help using a component?
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
To create or modify components from the Mistica library follow the next steps:
- Clone this repo
- Open
Package.swift - Place the new component under the
Componentsfolder. The component should have a proper definition by the design team. - 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.
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 skinTo 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.
- Open
Mistica.xcodeprojand create a new file inMisticaTestfolder. - 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.
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:
To check if everything is configured properly, try to execute the tests in main where all of them should pass.
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.