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.

Sign up for GitHub

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

Jump to bottom

Add linting for RST and MD files #1287

Merged
merged 3 commits into from
Oct 11, 2023
Merged

Add linting for RST and MD files #1287

merged 3 commits into from
Oct 11, 2023

Conversation

felixfontein
Copy link
Contributor

Uses rstcheck and markdownlint.

I don't have much experience with markdownlint, but it seems to work well and seems to be useful.

@felixfontein felixfontein force-pushed the ci branch 4 times, most recently from f33a587 to cacd6f5 Compare September 16, 2023 09:47
@felixfontein felixfontein requested a review from a team September 16, 2023 09:51
@hiddeco
Copy link
Member

hiddeco commented Sep 16, 2023

Think it would be good if these tools were available in the Makefile as well, to allow people to run them before CI catches things.

@onedr0p
Copy link
Contributor

onedr0p commented Sep 16, 2023 •
edited
Loading

I am not sure what the github action should be doing here...

  1. fail a PR when there are issues and have the author run the tools?
  2. open a PR with the changes after a PR is merged to main?
  3. when a pull request is opened or updated run these tools and commit back to the PR branch?
  4. or nothing and just have the workflow run logged with the issues found?

I tend to go with option 1 but it leaves the burden up to the PR author to fix the issues manually.

@felixfontein
Copy link
Contributor Author

@onedr0p right now the GHA does 1.; I'm not aware of any way to do 2. or 3.

I tend to go with option 1 but it leaves the burden up to the PR author to fix the issues manually.

I think that's acceptable, as long as we help them if they are not familiar with the doc formats (RST is especially error-prone, which IMO makes it even more important to add some validation).

@hiddeco
Copy link
Member

hiddeco commented Sep 16, 2023

Think 1 (or 4) is also the most desirable because linters can be wrong at times, as their observation lacks human reasoning which in terms of formatting may be different (for example, because of readability in edge cases). Otherwise, you may end up fighting a machine.

@felixfontein
Copy link
Contributor Author

Should I move out the docs changes into another PR? Might make reviewing / discussing easier.

hiddeco
hiddeco reviewed Sep 18, 2023
View reviewed changes
Makefile Outdated
.PHONY: checkrst
RST_FILES=$(shell find . -name '*.rst' | grep -v /vendor/ | sort)
checkrst: $(RST_FILES)
rstcheck $^
Copy link
Member

Choose a reason for hiding this comment

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

Would probably be good to have some type of command -v check here, with instructions on how to install these things (or targets to install them into BIN_DIR in case of absence).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've added a check in 8e1da49.

@felixfontein felixfontein mentioned this pull request Oct 9, 2023
Merged
@hiddeco hiddeco added this to the v3.8.1 milestone Oct 9, 2023
@hiddeco hiddeco changed the title Improve RST and MD files, and add linting for such files Add linting for RST and MD files Oct 10, 2023
@hiddeco
Copy link
Member

hiddeco commented Oct 10, 2023

@felixfontein this requires a rebase now that #1320 is merged. ✨

@felixfontein @hiddeco
Add workflow for rstcheck and mdl.
7b289aa 
Signed-off-by: Felix Fontein <felix@fontein.de>
@felixfontein @hiddeco
Add checkdocs, checkrst, and checkmd make targets.
3697768 
Signed-off-by: Felix Fontein <felix@fontein.de>
@felixfontein @hiddeco
Add section in CONTRIBUTING.md on docs changes.
eb1f4ec 
Signed-off-by: Felix Fontein <felix@fontein.de>
hiddeco
hiddeco approved these changes Oct 11, 2023
View reviewed changes
Copy link
Member

@hiddeco hiddeco left a comment

Choose a reason for hiding this comment

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

Thank you @felixfontein 🙇

@hiddeco hiddeco merged commit 76b6ffb into getsops:main Oct 11, 2023
10 checks passed
@felixfontein felixfontein deleted the ci branch October 11, 2023 07:06
@felixfontein
Copy link
Contributor Author

@hiddeco @onedr0p thanks for reviewing and merging!

mergify bot referenced this pull request in dbsystel/cdk-sops-secrets Oct 11, 2023
@renovate
fix(deps): update module github.com/getsops/sops/v3 to v3.8.1 (#878)
218ddf3 
[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
| [github.com/getsops/sops/v3](https://github.com/getsops/sops) | require | patch | `v3.8.0` -> `v3.8.1` |

---

### Release Notes

<details>
<summary>getsops/sops (github.com/getsops/sops/v3)</summary>

### [`v3.8.1`](https://github.com/getsops/sops/releases/tag/v3.8.1)

[Compare Source](https://github.com/getsops/sops/compare/v3.8.0...v3.8.1)

#### Note from the Maintainers

In this release of SOPS, we have focused on landing a variety of bug fixes to improve the overall user experience.

For a comprehensive list of changes, please refer to [`CHANGELOG.rst`](https://github.com/getsops/sops/blob/v3.8.1/CHANGELOG.rst).

##### Important Information for SOPS SDK Users

With the project transitioning from the Mozilla Foundation to the CNCF, the Go module path has been updated to reflect this change in ownership. If you use `go.mozilla.org/sops/v3` as a library, going forward, import the Go Module using `github.com/getsops/sops/v3`. Apart from this small adjustment, the SDK's API remains fully backward compatible.

For a one-liner to quickly implement this change throughout your codebase, please refer to: [https://github.com/getsops/sops/issues/1246#issuecomment-1625526429](https://github.com/getsops/sops/issues/1246#issuecomment-1625526429)

#### Installation

To install `sops`, download one of the pre-built binaries provided for your platform from the artifacts attached to this release.

For instance, if you are using Linux on an AMD64 architecture:

```shell

### Download the binary
curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.linux.amd64

### Move the binary in to your PATH
mv sops-v3.8.1.linux.amd64 /usr/local/bin/sops

### Make the binary executable
chmod +x /usr/local/bin/sops
```

##### Verify checksums file signature

The checksums file provided within the artifacts attached to this release is signed using [Cosign](https://docs.sigstore.dev/cosign/overview/) with GitHub OIDC. To validate the signature of this file, run the following commands:

```shell

### Download the checksums file, certificate and signature
curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.checksums.txt
curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.checksums.pem
curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.checksums.sig

### Verify the checksums file
cosign verify-blob sops-v3.8.1.checksums.txt \
  --certificate sops-v3.8.1.checksums.pem \
  --signature sops-v3.8.1.checksums.sig \
  --certificate-identity-regexp=https://github.com/getsops \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com
```

##### Verify binary integrity

To verify the integrity of the downloaded binary, you can utilize the checksums file after having validated its signature:

```shell

### Verify the binary using the checksums file
sha256sum -c sops-v3.8.1.checksums.txt --ignore-missing
```

##### Verify artifact provenance

The [SLSA provenance](https://slsa.dev/provenance/v0.2) of the binaries, packages, and SBOMs can be found within the artifacts associated with this release. It is presented through an [in-toto](https://in-toto.io/) link metadata file named `sops-v3.8.1.intoto.jsonl`. To verify the provenance of an artifact, you can utilize the [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier#artifacts) tool:

```shell

### Download the metadata file
curl -LO  https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.intoto.jsonl

### Verify the provenance of the artifact
slsa-verifier verify-artifact <artifact> \
  --provenance-path sops-v3.8.1.intoto.jsonl \
  --source-uri github.com/getsops/sops \
  --source-tag v3.8.1
```

#### Container Images

The `sops` binaries are also available as container images, based on Debian (slim) and Alpine Linux. The Debian-based container images include any dependencies which may be required to make use of certain key services, such as GnuPG, AWS KMS, Azure Key Vault, and Google Cloud KMS. The Alpine-based container images are smaller in size, but do not include these dependencies.

These container images are available for the following architectures: `linux/amd64` and `linux/arm64`.

##### GitHub Container Registry

-   `ghcr.io/getsops/sops:v3.8.1`
-   `ghcr.io/getsops/sops:v3.8.1-alpine`

##### Quay.io

-   `quay.io/getsops/sops:v3.8.1`
-   `quay.io/getsops/sops:v3.8.1-alpine`

##### Verify container image signature

The container images are signed using [Cosign](https://docs.sigstore.dev/cosign/overview/) with GitHub OIDC. To validate the signature of an image, run the following command:

```shell
cosign verify ghcr.io/getsops/sops:v3.8.1 \
  --certificate-identity-regexp=https://github.com/getsops \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  -o text
```

##### Verify container image provenance

The container images include [SLSA provenance](https://slsa.dev/provenance/v0.2) attestations. For more information around the verification of this, please refer to the [`slsa-verifier` documentation](https://github.com/slsa-framework/slsa-verifier#containers).

#### Software Bill of Materials

The Software Bill of Materials (SBOM) for each binary is accessible within the artifacts enclosed with this release. It is presented as an [SPDX](https://spdx.dev/) JSON file, formatted as `<binary>.spdx.sbom.json`.

#### What's Changed

-   build(deps): Bump the ci group with 3 updates by [@&#8203;dependabot](https://github.com/dependabot) in [https://github.com/getsops/sops/pull/1295](https://github.com/getsops/sops/pull/1295)
-   pgp: improve handling of GnuPG home dir by [@&#8203;hiddeco](https://github.com/hiddeco) in [https://github.com/getsops/sops/pull/1298](https://github.com/getsops/sops/pull/1298)
-   Delete sops encrypted file we don't have keys for by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1288](https://github.com/getsops/sops/pull/1288)
-   Improve handling of errors when binary store handles bad data by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1289](https://github.com/getsops/sops/pull/1289)
-   On macOS, prefer XDG_CONFIG_HOME over os.UserConfigDir() by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1291](https://github.com/getsops/sops/pull/1291)
-   Do not crash if an empty YAML file is encrypted by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1290](https://github.com/getsops/sops/pull/1290)
-   Fix descriptions of unencrypted-regex and encrypted-regex flags, and ensure unencrypted_regex is considered in config validation by [@&#8203;mitar](https://github.com/mitar) in [https://github.com/getsops/sops/pull/1300](https://github.com/getsops/sops/pull/1300)
-   build(deps): Bump the go group with 4 updates by [@&#8203;dependabot](https://github.com/dependabot) in [https://github.com/getsops/sops/pull/1306](https://github.com/getsops/sops/pull/1306)
-   build(deps): Bump the ci group with 1 update by [@&#8203;dependabot](https://github.com/dependabot) in [https://github.com/getsops/sops/pull/1301](https://github.com/getsops/sops/pull/1301)
-   Handle return values of dec.Token() to improve error messages by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1307](https://github.com/getsops/sops/pull/1307)
-   pgp: make error the last return value by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1310](https://github.com/getsops/sops/pull/1310)
-   pgp: do not require abs path for SopsGpgExecEnv  by [@&#8203;holiman](https://github.com/holiman) in [https://github.com/getsops/sops/pull/1309](https://github.com/getsops/sops/pull/1309)
-   decrypt: fix dropped error by [@&#8203;alrs](https://github.com/alrs) in [https://github.com/getsops/sops/pull/1304](https://github.com/getsops/sops/pull/1304)
-   Handle errors by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1311](https://github.com/getsops/sops/pull/1311)
-   Report key rotation errors by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1317](https://github.com/getsops/sops/pull/1317)
-   cmd/sops/main.go: make sure to wrap raw errors with toExitError() by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1318](https://github.com/getsops/sops/pull/1318)
-   build(deps): Bump the go group with 7 updates by [@&#8203;dependabot](https://github.com/dependabot) in [https://github.com/getsops/sops/pull/1319](https://github.com/getsops/sops/pull/1319)
-   Enrich AWS authentication documentation by [@&#8203;nsantiago2719](https://github.com/nsantiago2719) in [https://github.com/getsops/sops/pull/1272](https://github.com/getsops/sops/pull/1272)
-   Better error reporting for missing gpg binary by [@&#8203;makkes](https://github.com/makkes) in [https://github.com/getsops/sops/pull/1286](https://github.com/getsops/sops/pull/1286)
-   Improve RST and MD files by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1320](https://github.com/getsops/sops/pull/1320)
-   Add linting for RST and MD files by [@&#8203;felixfontein](https://github.com/felixfontein) in [https://github.com/getsops/sops/pull/1287](https://github.com/getsops/sops/pull/1287)
-   Update dependencies by [@&#8203;hiddeco](https://github.com/hiddeco) in [https://github.com/getsops/sops/pull/1325](https://github.com/getsops/sops/pull/1325)
-   Prepare v3.8.1 by [@&#8203;hiddeco](https://github.com/hiddeco) in [https://github.com/getsops/sops/pull/1324](https://github.com/getsops/sops/pull/1324)

#### New Contributors

-   [@&#8203;mitar](https://github.com/mitar) made their first contribution in [https://github.com/getsops/sops/pull/1300](https://github.com/getsops/sops/pull/1300)
-   [@&#8203;holiman](https://github.com/holiman) made their first contribution in [https://github.com/getsops/sops/pull/1309](https://github.com/getsops/sops/pull/1309)
-   [@&#8203;alrs](https://github.com/alrs) made their first contribution in [https://github.com/getsops/sops/pull/1304](https://github.com/getsops/sops/pull/1304)
-   [@&#8203;nsantiago2719](https://github.com/nsantiago2719) made their first contribution in [https://github.com/getsops/sops/pull/1272](https://github.com/getsops/sops/pull/1272)
-   [@&#8203;makkes](https://github.com/makkes) made their first contribution in [https://github.com/getsops/sops/pull/1286](https://github.com/getsops/sops/pull/1286)

**Full Changelog**: getsops/sops@v3.8.0...v3.8.1

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] If you want to rebase/retry this PR, check this box

---

This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/markussiebert/cdk-sops-secrets).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@hiddeco hiddeco hiddeco approved these changes

Assignees
No one assigned
Labels
area/CI
Projects
None yet
Milestone
v3.8.1
Development

Successfully merging this pull request may close these issues.
3 participants
@felixfontein @hiddeco @onedr0p