repo: Add README #13

minor-fixes · 2024-07-23T15:15:54Z

This change adds the beginning of a README, which covers basic topics such as:

how to build
how to report vulnerabilities
how to contribute

Tested: N/A

Bug: linear/CUS-360

README.md

jayconrod · 2024-07-23T17:43:57Z

README.md

+This repository contains source for the authentication CLI that manages
+credentials for EngFlow clusters.


Rephrase to emphasize the problem this solves for user:

Suggested change

This repository contains source for the authentication CLI that manages

credentials for EngFlow clusters.

This repository provides `engflow_auth`, a [Bazel credential helper](https://blog.engflow.com/2023/10/20/secure-builds-with-credential-helpers/) that helps you automatically obtain and securely store EngFlow authentication tokens.

Done, thanks!

README.md

jayconrod · 2024-07-23T17:46:57Z

README.md

+
+## Reporting Issues
+
+To report bugs/vulnerabilities on `engflow_auth`, please send an email to


For normal bugs and feature requests, I think it's easiest to use GitHub issues.

For security vulnerability reports, [email protected] is a good idea. That should be used when the issue shouldn't be disclosed to the open internet until it's fixed.

For normal bugs and feature requests, I think it's easiest to use GitHub issues.

We have issues disabled on this repo (I guess I was wrong about issues being coupled with pull requests!) and I think that's the right choice - issues invite a sense of urgency/SLA that we may not be ready for.

For features/bugs, I don't mind going through DSE's so that the rest of the org is aware, and priority is assigned correctly. Though - it may be beneficial to have some line of communication as a "fast path" for quicker turnaround, or to hear feedback from people who may not be customers

Either way is fine I think. We do have a well-established support channel for the platform, and we can use that for the CLI.

Mainly I think it's important to distinguish security vulnerability reports that need to be kept secret from everything else.

I think it's important here to distinguish two separate channels. [email protected] is only for vulnerability reports that need to be handled discreetly. All other bugs and feature requests should go through DSE.

In our public documentation, we do have https://docs.engflow.com/support/index.html to explain our support channels (though it appears that page could use some clean up).

Ok - I think all the reports will end up in the non-urgent category, so I linked deeper to https://docs.engflow.com/support/get-day-to-day-support.howto.html - PTAL

README.md

jayconrod · 2024-07-23T17:54:01Z

README.md

+
+## Building
+
+The CLI can be built via either the Golang toolchain or Bazel; released binaries


I apologize, I'm give the most pedantic of nits here.

Use "Go" as the name of the language. "Golang" is not an official name and shouldn't be used in a formal context like documentation. https://go.dev/doc/faq#go_or_golang

Suggested change

The CLI can be built via either the Golang toolchain or Bazel; released binaries

The CLI can be built via either the Go toolchain or Bazel; released binaries

README.md

jayconrod · 2024-07-23T18:01:06Z

README.md

+Since we have no CLA set up for `engflow_auth`, we are not accepting pull
+requests from external contributors at this time.


Suggested change

Since we have no CLA set up for `engflow_auth`, we are not accepting pull

requests from external contributors at this time.

We are not accepting pull requests from external contributors at this time.

Let's omit the rationale here. We could set up a CLA if we wanted to, but most changes here also require a change to a proprietary server-side component, so we want to decide and coordinate those changes ourselves.

Made the rationale a bit more vague - no rationale sounds a bit standoffish to me, which I'd like to avoid

jayconrod · 2024-07-23T19:57:16Z

README.md

+   instance:
+
+   ```
+   build:example --credential_helper=example.cluster.engflow.com=/path/to/engflow_auth


Use engflow as the config name rather than example, following https://docs.engflow.com/re/client/bazel-first-time.html#4-set-up-bazelrc. The user needs a bunch of other flags like --remote_executor, and we use engflow as the configuration name in those instructions.

jayconrod · 2024-07-23T19:59:05Z

README.md

+
+### Use
+
+1. Each day, run `engflow_auth login [CLUSTER URL]` each day to obtain an auth


This feels a little awkward as a list with only one step. Maybe make "click the URL" a second step, or just format as a paragraph.

Also "each day" is here twice in the same sentence. Drop at least one.

Whoops! Fixed

jayconrod · 2024-07-23T20:02:39Z

README.md

+
+## Reporting Issues
+
+To report bugs/vulnerabilities on `engflow_auth`, please send an email to


I think it's important here to distinguish two separate channels. [email protected] is only for vulnerability reports that need to be handled discreetly. All other bugs and feature requests should go through DSE.

In our public documentation, we do have https://docs.engflow.com/support/index.html to explain our support channels (though it appears that page could use some clean up).

jayconrod · 2024-07-23T20:23:41Z

Still needs resolution, looks good otherwise.

I think it's important here to distinguish two separate channels. [email protected] is only for vulnerability reports that need to be handled discreetly. All other bugs and feature requests should go through DSE.

In our public documentation, we do have https://docs.engflow.com/support/index.html to explain our support channels (though it appears that page could use some clean up).

This change adds the beginning of a README, which covers basic topics such as: * how to build * how to report vulnerabilities * how to contribute Tested: N/A Bug: linear/CUS-360

jayconrod

Looks good!

minor-fixes requested a review from jayconrod July 23, 2024 15:16

minor-fixes commented Jul 23, 2024

View reviewed changes

README.md Show resolved Hide resolved

README.md Show resolved Hide resolved

jayconrod reviewed Jul 23, 2024

View reviewed changes

minor-fixes force-pushed the scott/CUS-360 branch from d9f93b6 to 59d0ce3 Compare July 23, 2024 19:51

jayconrod reviewed Jul 23, 2024

View reviewed changes

minor-fixes force-pushed the scott/CUS-360 branch from 59d0ce3 to 3d5fd80 Compare July 23, 2024 20:10

repo: Add README

e7f021c

This change adds the beginning of a README, which covers basic topics such as: * how to build * how to report vulnerabilities * how to contribute Tested: N/A Bug: linear/CUS-360

minor-fixes force-pushed the scott/CUS-360 branch from 3d5fd80 to e7f021c Compare July 23, 2024 20:30

jayconrod approved these changes Jul 23, 2024

View reviewed changes

minor-fixes merged commit 7cdd7a5 into main Jul 24, 2024
4 checks passed

minor-fixes deleted the scott/CUS-360 branch July 24, 2024 00:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

repo: Add README #13

repo: Add README #13

minor-fixes commented Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

minor-fixes Jul 23, 2024

jayconrod Jul 23, 2024

jayconrod commented Jul 23, 2024

jayconrod left a comment

		This repository contains source for the authentication CLI that manages
		credentials for EngFlow clusters.

	This repository contains source for the authentication CLI that manages
	credentials for EngFlow clusters.
	This repository provides `engflow_auth`, a [Bazel credential helper](https://blog.engflow.com/2023/10/20/secure-builds-with-credential-helpers/) that helps you automatically obtain and securely store EngFlow authentication tokens.


		## Reporting Issues

		To report bugs/vulnerabilities on `engflow_auth`, please send an email to


		## Building

		The CLI can be built via either the Golang toolchain or Bazel; released binaries

	The CLI can be built via either the Golang toolchain or Bazel; released binaries
	The CLI can be built via either the Go toolchain or Bazel; released binaries

		Since we have no CLA set up for `engflow_auth`, we are not accepting pull
		requests from external contributors at this time.

	Since we have no CLA set up for `engflow_auth`, we are not accepting pull
	requests from external contributors at this time.
	We are not accepting pull requests from external contributors at this time.


		### Use

		1. Each day, run `engflow_auth login [CLUSTER URL]` each day to obtain an auth

repo: Add README #13

repo: Add README #13

Conversation

minor-fixes commented Jul 23, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jayconrod commented Jul 23, 2024

jayconrod left a comment

Choose a reason for hiding this comment