Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add DocC catalog and README #3

Merged
merged 4 commits into from
Sep 30, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .spi.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
version: 1
builder:
configs:
- documentation_targets: [GRPCProtobuf]
swift_version: 6.0
21 changes: 3 additions & 18 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,4 @@
# How to contribute
# Contributing

We definitely welcome patches and contributions to grpc-swift! Please read the gRPC
organization's [governance rules](https://github.com/grpc/grpc-community/blob/main/governance.md)
and [contribution guidelines](https://github.com/grpc/grpc-community/blob/main/CONTRIBUTING.md) before proceeding.

Here are some guidelines and information about how to participate.

## Getting started

### Legal requirements

In order to protect both you and ourselves, you will need to sign the
[Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf).

### Technical requirements

Please see the [main gRPC repository](https://github.com/grpc/grpc) for
more information about gRPC.
Please refer to the contributing guide in the
[`grpc/grpc-swift`](https://github.com/grpc/grpc-swift) repository.
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# gRPC Swift Protobuf

This repository contains integrations with [SwiftProtobuf][gh-swift-protobuf]
for [gRPC Swift][gh-grpc-swift-protobuf].

- 📚 **Documentation** is available on the [Swift Package Index][spi-grpc-swift-protobuf]
- 🎓 **Tutorials** are available in the documentation for `grpc/grpc-swift` on
the [Swift Package Index][spi-grpc-swift].
- 💻 **Examples** are available in the `Examples` directory of the
[`grpc/grpc-swift`](https://github.com/grpc/grpc-swift) repository
- 🚀 **Contributions** are welcome, pleasee see [CONTRIBUTING.md](CONTRIBUTING.md)
glbrntt marked this conversation as resolved.
Show resolved Hide resolved
- 🪪 **License** is Apache 2.0, repeated in [LICENSE](License)
- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md)

[gh-swift-protobuf]: https://github.com/apple/swift-protobuf
[gh-grpc-swift-protobuf]: https://github.com/grpc/grpc-swift-protobuf
[spi-grpc-swift]: https://swiftpackageindex.com/grpc/grpc-swift/documentation
[spi-grpc-swift-protobuf]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation
46 changes: 2 additions & 44 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,4 @@
# Security

This document specifies the security process for gRPC Swift.

## Disclosures

### Private Disclosure Process

The gRPC Swift team asks that known and suspected vulnerabilities be
privately and responsibly disclosed by emailing
[[email protected]](mailto:[email protected])
with the [details usually included with bug reports][issue-template].
**Do not file a public issue.**

#### When to report a vulnerability

* You think you have discovered a potential security vulnerability in gRPC
Swift.
* You are unsure how a vulnerability affects gRPC Swift.

#### What happens next?

* A member of the team will acknowledge receipt of the report within 3
working days (United Kingdom). This may include a request for additional
information about reproducing the vulnerability.
* We will privately inform the Swift Server Work Group ([SSWG][sswg]) of the
vulnerability within 10 days of the report as per their [security
guidelines][sswg-security].
* Once we have identified a fix we may ask you to validate it. We aim to do this
within 30 days. In some cases this may not be possible, for example when the
vulnerability exists at the protocol level and the industry must coordinate on
the disclosure process.
* If a CVE number is required, one will be requested from [MITRE][mitre]
providing you with full credit for the discovery.
* We will decide on a planned release date and let you know when it is.
* Prior to release, we will inform major dependents that a security-related
patch is impending.
* Once the fix has been released we will publish a security advisory on GitHub
and the [SSWG][sswg] will announce the vulnerability on the [Swift
forums][swift-forums-sec].

[issue-template]: https://github.com/grpc/grpc-swift/blob/main/.github/ISSUE_TEMPLATE/BUG_REPORT.md
[sswg]: https://github.com/swift-server/sswg
[sswg-security]: https://github.com/swift-server/sswg/blob/main/process/incubation.md#security-best-practices
[swift-forums-sec]: https://forums.swift.org/c/server/security-updates/
[mitre]: https://cveform.mitre.org/
Please refer to [SECURITY.md] in the
[`grpc/grpc-swift`](https://github.com/grpc/grpc-swift) repository.
20 changes: 20 additions & 0 deletions Sources/GRPCProtobuf/Documentation.docc/Documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# ``GRPCProtobuf``

A package integrating Swift Protobuf with gRPC Swift.

## Overview

This package provides two products:
- ``GRPCProtobuf``, a module providing runtime serialization and deserialization components for
[SwiftProtobuf](https://github.com/apple/swift-protobuf).
- `protoc-gen-grpc-swift`, an executable which is a plugin for `protoc`, the Protocol Buffers
compiler. An article describing how to generate gRPC Swift stubs using it is available with the
`grpc-swift` documentation on the [Swift Package
Index](https://swiftpackageindex.com/grpc/grpc-swift/documentation).

## Topics
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want this empty section?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes: if you don't have a ## Topic, DocC will insert it for you at the end of the doc.


### Serialization

- ``ProtobufSerializer``
- ``ProtobufDeserializer``
Comment on lines +19 to +20
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want some more detail here?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, we're just listing links to types (these are the only ones) – DocC renders a summary of each inline:

Screenshot 2024-09-30 at 11 13 46

Loading