First iteration of documentation and Lint workflow #1
Conversation
goncalo-frade-iohk
requested review from
elribonazo,
hamada147,
FabioPinheiro,
zejaco,
antonbaliasnikov and
yshyn-iohk
There was a problem hiding this comment.
After you merge I will copy the CONTRIBUTING.md into https://github.com/input-output-hk/atala-prism-building-blocks
|
@yshyn-iohk any opinion on the squashed commits? Is this correct? |
Hi @goncalo-frade-iohk , no, the approach you follow is not correct. You have 2 options for merging PRs:
that should be used accordingly for 2 different use cases. Use case 1 - Squash and merge In this case, all commits will be squashed automatically by GitHub in 1 commit with the commit message you specify in the PR title: In this case:
Use this when you have related changes in one part of the project with the same purpose. For example, in the case of this PR, if using option 1, you should create 2 different PRs with the following titles:
Use case 2 - Rebase and merge In this case, commits won't be squashed. And all the commits history from your branch will be merged to the In this case:
As the result, in your case, the commits history of your branch should contain the following commits:
And both of them will be merged into the |
|
@goncalo-frade-iohk , Conventional Commits helps us to split changes accordingly to the purpose of these changes. In your example, you have a branch called So, please, separate changes by several Conventional commits in this PR, or create 2 different PRs accordingly to the purpose of the changes you make. |
.github/workflows/SwiftLint.yml
Outdated
| branches: | ||
| - master | ||
| pull_request: | ||
| branches: |
There was a problem hiding this comment.
For pull_request, you will run CI only if PR is opened to be merged to master / main branch.
Why is that? Sometimes, PRs can be used to make changes in other branches that also can be useful and CI is important to be executed. I suggest to remove branches from the pull_request target.
There was a problem hiding this comment.
IMO CI is for hard and sanity checks, so everyone is relaxed when code is going into long live branches (master, main, development "if gitflow"). This process requires resources that are limited (MacOS virtual machines we got a few for all the organization), there were times I was waiting for more than an hour.
Having this processes for any PR would be overkill and not give much.
| @@ -0,0 +1,109 @@ | |||
| disabled_rules: | |||
There was a problem hiding this comment.
Why these rules are disabled? Please, add some comments.
There was a problem hiding this comment.
IMO explaining each rule disabled or opted in is not a good process.
This are the rules we were previously using in all other Swift projects.
Also on CONTRIBUTING.md there is a topic about this matter, if there is a change needed around this file then I would say in the future other contributors can provide a PR with changes.
Meanwhile if there is really interest in knowing what are the disabled and option rules. You can check them in here: https://realm.github.io/SwiftLint/rule-directory.html
.github/workflows/SwiftLint.yml
Outdated
| @@ -0,0 +1,22 @@ | |||
| name: SwiftLint | |||
There was a problem hiding this comment.
In quality, we also provided a more general and common variant of the linter:
I'm not sure that swiftlint is better.
There was a problem hiding this comment.
swiftlint IS the linter for Swift. Used in general probably by almost all the community. Megalinter just puts all the linters in one, also internally by their documentation they use SwiftLint.
Now we can switch to use megalinter so all the projects use the same but internally it will just use swiftlint.
There was a problem hiding this comment.
Yes, but in this case, we don't need swiftlint to be separately configured, we could use megalinter for everything as our standard across all the repositories.
There was a problem hiding this comment.
Ok on the mega linter process that you provided. I don't think Lint should ever do automatic fixes in CI and commit them.
This should be done always by the developer.
There was a problem hiding this comment.
I will now go forward with SwiftLint workflow. But I think we can make this change, I don't mind using megalinter, just don't totally agree with it committing changes :)
| @@ -0,0 +1,2 @@ | |||
| --disable trailingCommas,unusedArguments | |||
There was a problem hiding this comment.
Why trailingCommas,unusedArguments are disabled?
There was a problem hiding this comment.
Same as with SwiftLint rules. If you need more information you can check here: https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md
As they are only 2 I can quickly explain:
trailing commas - they basically on arrays add a comma on the last member, this conflicts with SwiftLint
let array = [
foo,
bar,
- baz
]
let array = [
foo,
bar,
+ baz,
]
- unusedArguments - do an annoying thing that if you build just to check something it deletes the name of the fields you still didn't used.
- func foo(_ bar: Int) {
...
}
+ func foo(_: Int) {
...
}
There was a problem hiding this comment.
Could you, please, explain why trailing commas conflict with SwiftLint? Trailing commas are the good thing in Swift?
There was a problem hiding this comment.
Could you, please, explain why trailing commas conflict with SwiftLint?
Because SwiftLint also has this rule https://realm.github.io/SwiftLint/trailing_comma.html that can be deactivated.
Trailing commas are the good thing in Swift?
It really doesn't matter. It's has to be with the style guide pattern, some will like it others will not. The style guide we use just went for this way, but as SwiftFormat does one way and SwiftLint does the other by default. One of them need to be deactivated.
@FabioPinheiro , @goncalo-frade-iohk do you think we should copy this between the repositories? Does this make sense? I thought we should have the common stuff in one place, in the main repository, and other repositories should just point to this. |
@antonbaliasnikov I don't mind it can be a single repo with this. |
Then, please, put it in one main repository and give the link to it in the right places. |
What is the main repository? I don't think it is |
Ok I thought better about this, and im not sure of one thing. Since So it cannot be |
goncalo-frade-iohk
force-pushed
the
feature/UpdateReadmeContributing
branch
from
4c0b25b to
e47ae81
Compare
goncalo-frade-iohk
changed the title
The Mintfile defines the development dependency software the project requires
goncalo-frade-iohk
force-pushed
the
feature/UpdateReadmeContributing
branch
2 times, most recently
from
6577e59 to
63aaf75
Compare
|
I removed the SwiftLint CI process from here since @antonbaliasnikov gave the |
| # Contributing to Atala PRISM Swift SDK | ||
|
|
||
| :rocket::tada: First off, thanks for taking the time to contribute! :tada::rocket: | ||
| The following is a set of guidelines for contributing to Atala PRISM Swift SDK. These are mostly guidelines. Use your best judgment, and feel free to propose changes to this document in a pull request. |
There was a problem hiding this comment.
The following are guidelines for contributing to the Atala PRISM Swift SDK.
|
|
||
| ### Atala PRISM | ||
|
|
||
| Atala PRISM is a self-sovereign identity (SSI) platform and service suite for verifiable data and digital identity. Built on Cardano, it offers core infrastructure for issuing DIDs (Decentralized identifiers) and verifiable credentials, alongside tools and frameworks to help expand your ecosystem. |
There was a problem hiding this comment.
Atala PRISM is a Self-Sovereign Identity (SSI) platform and service suite for verifiable data and digital identity. Built on Cardano, it offers the core infrastructure for issuing Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs), alongside tools and frameworks to help expand your ecosystem.
| Atala PRISM is a self-sovereign identity (SSI) platform and service suite for verifiable data and digital identity. Built on Cardano, it offers core infrastructure for issuing DIDs (Decentralized identifiers) and verifiable credentials, alongside tools and frameworks to help expand your ecosystem. | ||
| The complete platform is separated in multiple repositories: | ||
|
|
||
| * [atala-prism-apollo](--) - Repo for the Apollo Building Block, this contains the collecion of the cryptographic methods used all around Atala PRISM. |
There was a problem hiding this comment.
Repo for the Apollo Building Block contains the collection of the cryptographic methods used by Atala PRISM.
|
|
||
| ### Atala PRISM Swift SDK | ||
|
|
||
| Atala PRISM Swift software development kit will help adoption within Apple frameworks by providing key functionalities. For more information around the SDK please have a look at the [Readme](https://github.com/input-output-hk/atala-prism-swift-sdk/blob/main/README.md) |
There was a problem hiding this comment.
Atala PRISM's Swift software development kit will help adoption within Apple frameworks by providing key functionalities. For more information about the SDK, please review the README.
|
|
||
| ### Your First Code Contribution | ||
|
|
||
| Unsure where to begin contributing to Atala PRISM Swift SDK? You can start by looking through the [Readme](https://github.com/input-output-hk/atala-prism-swift-sdk/blob/main/README.md) that provides all the steps to setup your environment. |
|
|
||
| ### Pull Requests | ||
|
|
||
| The process described here has several goals: |
There was a problem hiding this comment.
The process described has several goals:
|
|
||
| 1. Follow all instructions in [the template](PULL_REQUEST_TEMPLATE.md) | ||
| 2. Follow the [styleguides](#styleguides) | ||
| 3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details> |
There was a problem hiding this comment.
- After you submit your pull request, verify that all status checks are passing
What if the status checks are failing?
If a status check is failing, and you believe the failure is unrelated to your change, please comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, we will open an issue to track that problem with our status check suite.
| 2. Follow the [styleguides](#styleguides) | ||
| 3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details> | ||
|
|
||
| While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. |
There was a problem hiding this comment.
While the prerequisites above must be satisfied before your pull request gets reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes, before your pull request gets accepted.
|
|
||
| ### Reporting Bugs | ||
|
|
||
| This section guides you through submitting a bug report for Atala PRISM Swift SDK. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. |
There was a problem hiding this comment.
This section guides you through submitting a bug report for the Atala PRISM Swift SDK. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.
|
|
||
| This section guides you through submitting a bug report for Atala PRISM Swift SDK. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. | ||
|
|
||
| Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out [the required template](https://github.com/input-output-hk/atala-prism-swift-sdk/blob/main/.github/ISSUE_TEMPLATE/bug_report.md), the information it asks for helps us resolve issues faster. |
There was a problem hiding this comment.
Before creating bug reports, please check this list as you might find out that you don't need to create one. When you create a bug report, please include as many details as possible. Fill out the required template with the information it asks for helps us resolve issues faster.
|
|
||
| Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out [the required template](https://github.com/input-output-hk/atala-prism-swift-sdk/blob/main/.github/ISSUE_TEMPLATE/bug_report.md), the information it asks for helps us resolve issues faster. | ||
|
|
||
| > **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. |
There was a problem hiding this comment.
Note: If you find a Closed issue that seems like it is the same thing you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
| > **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. | ||
|
|
||
| * **You might be able to find the cause of the problem and fix things yourself by Debugging**. Most importantly, check if you can reproduce the problem in the latest version. | ||
| * **Check the [Readme](https://github.com/input-output-hk/atala-prism-swift-sdk/blob/main/README.md) ** if you have problems on the setup and the [discussions](https://github.com/input-output-hk/atala-prism-swift-sdk/discussions)** for a list of common questions and problems. |
There was a problem hiding this comment.
Check the Readme ** if you have problems with the setup and the discussions** for a list of common questions and issues.
| Explain the problem and include additional details to help maintainers reproduce the problem: | ||
|
|
||
| * **Use a clear and descriptive title** for the issue to identify the problem. | ||
| * **Describe the exact steps which reproduce the problem** in as many details as possible. |
There was a problem hiding this comment.
- Describe the exact steps which reproduce the problem in as much detail as possible.
|
|
||
| * **Use a clear and descriptive title** for the issue to identify the problem. | ||
| * **Describe the exact steps which reproduce the problem** in as many details as possible. | ||
| * **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). |
There was a problem hiding this comment.
Provide specific examples to demonstrate the steps. Include links to files, GitHub projects, or copy/pasteable snippets you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
| * **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. | ||
| * **Explain which behavior you expected to see instead and why.** | ||
| * **If you're reporting that the SDK crashed**, include a crash report with a stack trace from the operating system. On macOS, the crash report will be available in `Console.app` under "Diagnostic and usage information" > "User diagnostic reports". Include the crash report in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist. | ||
| * **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below. |
There was a problem hiding this comment.
- **If a specific action ** didn't trigger the problem, describe what you were doing before the problem happened and share more information using the guidelines below.
|
|
||
| Provide more context by answering these questions: | ||
|
|
||
| * **Did the problem start happening recently** (e.g. after updating to a new version of the SDK) or was this always a problem? |
There was a problem hiding this comment.
- Did the problem start happening recently (e.g., after updating to a new version of the SDK), or was this always a problem?
|
|
||
| * **Did the problem start happening recently** (e.g. after updating to a new version of the SDK) or was this always a problem? | ||
| * If the problem started happening recently, **can you reproduce the problem in an older version of the SDK?** What's the most recent version in which the problem doesn't happen? | ||
| * **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. |
There was a problem hiding this comment.
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it usually happens.
|
|
||
| ### Suggesting Enhancements | ||
|
|
||
| This section guides you through submitting an enhancement suggestion for the SDK, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. |
There was a problem hiding this comment.
This section guides you through submitting an enhancement suggestion for the SDK, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your request:pencil: and find related suggestions :mag_right:.
| Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](https://github.com/input-output-hk/atala-prism-swift-sdk/blob/main/.github/ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed. | ||
|
|
||
| * Most importantly, **check if you're using the lattest version.** | ||
| * **Perform a cursory search** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. |
There was a problem hiding this comment.
- Perform a cursory search to see if a similar enhancement exists. If one does, add a comment to the existing issue instead of opening a new one.
| Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue on that repository and provide the following information: | ||
|
|
||
| * **Use a clear and descriptive title** for the issue to identify the suggestion. | ||
| * **Provide a step-by-step description of the suggested enhancement** in as many details as possible. |
There was a problem hiding this comment.
- Provide a detailed description of the suggested enhancement in as much detail as possible.
| # Welcome to Atala PRISM Swift SDK | ||
|
|
||
| The following will explain how to use the SDK in your project, how to prepare your development environment if you wish to contribute and some basic considerations around the project. |
There was a problem hiding this comment.
The following will explain how to use the SDK in your project, how to prepare your development environment if you wish to contribute, and some basic considerations around the project.
| The following will explain how to use the SDK in your project, how to prepare your development environment if you wish to contribute and some basic considerations around the project. | ||
|
|
||
| This SDK provides a library and documentation for developers to build Apple connected SSI applications with Atala PRISM. |
There was a problem hiding this comment.
This SDK provides a library and documentation for developers to build Apple-connected SSI applications with Atala PRISM.
| * [__Mercury__](WIP) Building block that will provide a set of secure, standards based communications protocols to establish and manage trusted, peer-to-peer connections and interactions between DIDs in a transport agnostic and interoperable manner. | ||
| * [__Pluto__](WIP) Building block that will provide an interface for storage operations to securely store, manage, and recover verifiable data linked to DIDs in a portable, storage agnostic manner. | ||
| * [__Experience__](WIP) Set of commonly used operations or features that use 1 or multiple building blocks. |
There was a problem hiding this comment.
- Castor building block will provide a suite of Decentralized Identiifier (DID) operations to create, manage and resolve standards-based DIDs in a user-controlled manner.
- Pollux building block will provide a suite of credential operations to issue, manage and verify standards based on verifiable credentials in a privacy-preserving manner.
- Mercury building block will provide a set of secure, standards-based communications protocols to establish and manage trusted, peer-to-peer connections and interactions between DIDs in a transport agnostic and interoperable manner.
- Pluto building block will provide an interface for storage operations to store, manage securely, and recover verifiable data linked to DIDs in a portable, storage agnostic manner.
- Experience Set of commonly used operations or features that use one or multiple building blocks.
|
|
||
| To get started with the Atala PRISM Swift SDK, you can set up the SDK and start a new project, or you can integrate the SDK in an existing project. | ||
| To use the SDK you will need the following installed on your development machine: |
There was a problem hiding this comment.
To get started with the Atala PRISM Swift SDK, you can set up the SDK and create a new project or integrate the SDK into an existing project.
To use the SDK, you will need the following installed on your development machine:
| ### Atala PRISM | ||
|
|
||
| Atala PRISM is a self-sovereign identity (SSI) platform and service suite for verifiable data and digital identity. Built on Cardano, it offers core infrastructure for issuing DIDs (Decentralized identifiers) and verifiable credentials, alongside tools and frameworks to help expand your ecosystem. |
There was a problem hiding this comment.
Atala PRISM is a Self-Sovereign Identity (SSI) platform and service suite for verifiable data and digital identity. Built on Cardano, it offers the core infrastructure for issuing DIDs and verifiable credentials, alongside tools and frameworks to help expand your ecosystem.
| ### Documentation | ||
|
|
||
| The SDK will provide 2 kinds of documentation, a more general documentation describing architecture decisions and an API documentation. It will also provide within time samples on how to use the SDK. A Docx documentation will be provided for in Xcode helpful documentation as well as a website. |
There was a problem hiding this comment.
The SDK will provide two kinds of documentation, more general documentation describing architecture decisions and API documentation. In time, it will offer samples on how to use the SDK. An included document provides Xcode helpful documentation and a website.
!! Please review this comment thoroughly, the last sentence was a little hard to read, I think I cleaned it up appropriately. Ensure the original message is maintained.
No description provided.