7.2 KiB

Raw Blame History

sidebarDepth	search
2	false

Contributing

Thanks for helping to make Fx better for everyone!

If you'd like to add new exported APIs, please open an issue describing your proposal. Discussing API changes ahead of time makes pull request review much smoother.

::: tip You'll need to sign Uber's CLA before we can accept any of your contributions. If necessary, a bot will remind you to accept the CLA when you open your pull request. :::

Contribute code

Set up your local development environment to contribute to Fx.

Fork, then clone the repository.
```bash git clone https://github.com/your_github_username/fx.git cd fx git remote add upstream https://github.com/uber-go/fx.git git fetch upstream ``` ```bash gh repo fork --clone uber-go/fx ```
Install Fx's dependencies:
```
go mod download
```
Verify that tests and other checks pass locally.
```
make lint
make test
```
Note that for make lint to work, you must be using the latest stable version of Go. If you're on an older version, you can still contribute your change, but we may discover style violations when you open the pull request.

Next, make your changes.

Create a new feature branch.

git checkout master
git pull
git checkout -b cool_new_feature

Make your changes, and verify that all tests and lints still pass.
```
$EDITOR app.go
make lint
make test
```
When you're satisfied with the change, push it to your fork and make a pull request.
```bash git push origin cool_new_feature # Open a PR at https://github.com/uber-go/fx/compare ``` ```bash gh pr create ```

At this point, you're waiting on us to review your changes. We try to respond to issues and pull requests within a few business days, and we may suggest some improvements or alternatives. Once your changes are approved, one of the project maintainers will merge them.

The review process will go more smoothly if you:

add tests for new functionality
write a good commit message
maintain backward compatibility
follow our style guide

Contribute documentation

To contribute documentation to Fx,

Set up your local development environment as you would to contribute code.
Install the documentation website dependencies.
```
cd docs
yarn install
```
Run the development server.
```
yarn dev
```
Make your changes.

Documentation changes should adhere to the guidance laid out below.

Document by purpose

Documentation is organized in one of the following categories.

Tutorials: These hold step-by-step instructions for an end-to-end project that a beginner could follow along to. Don't spend time explaining things. If explanations are available elsewhere, link to them. These are entry points to answer the prompt, "I don't know what Fx is, show me what it can do," so there won't be too many of these.
Explanations: These hold long-form explanations of concepts and ideas. These are intended to build an understanding of Fx. Feel free to go wild here--use learning aids like diagrams, tables, etc.
How-tos: These are step-by-step instructions for a specific problem. Unlike tutorials, these are not meant to be end-to-end. Feel free to leave things out, make assumptions, or provide options ("if you're doing this, do this"). As with tutorials, don't spend time explaining; link to explanations elsewhere.

As an example,

A tutorial will use lifecycle hooks as part of a larger set of instructions for a full end-to-end application.
An explanation will explain what lifecycle hooks are, how they work, when and how you should use them, and link to relevant APIs and guides.
A how-to guide will demonstrate how to use lifecycle hooks with an HTTP server, a gRPC server, etc.

Explanations and how-to guides are often on the same page, but they should be in distinct sections.

This separation is inspired by the Divio documentation system,

Formatting

ATX-style headers

Use ATX-style headers (#-prefixed), not Setext-style (underlined with === or ---).

Bad header
==========

## Good header

Semantic Line Breaks

Do not write overly long lines of text
Do not "reflow" Markdown paragraphs
Do use Semantic Line Breaks to break these lines down

This is a bad paragraph because it's really long, all on one line. When I open this in a text editor, I'll have to scroll right.

This is a bad paragraph because even though it's not all one one line, it adds
line breaks when it reaches the line length limit. This means that anytime I
change anything in this paragraph, I have to "reflow" it, which will change
other lines and make the change I'm making more difficult to review.

This is a good paragraph. It uses semantic line breaks.
I can add words or modify an existing sentence,
or even parts of a sentence,
easily and without affecting other lines.
When I change something, the actual change I made is easy to review.
Markdown will reflow this into a "normal" pargraph when rendering.

Test everything

All code samples in documentation must be buildable and testable.

To aid in this, we have two tools:

mdox
the region shell script

mdox

mdox is a Markdown file formatter that includes support for running a command and using its output as part of a code block. To use this, declare a regular code block and tag it with mdoc-exec.

```go mdox-exec='cat foo.go'
// ...

The contents of the code block will be replaced with the output of the command when you run make fmt in the docs directory. make check will ensure that the contents are up-to-date.

The command runs with the working directory set to docs/. Store code samples in ex/ and reference them directly.

region

The region shell script is a command intended to be used with mdox-exec.

USAGE: region FILE REGION1 REGION2 ...

Extracts text from FILE marked by "// region" blocks.

For example, given the file:

foo
// region myregion
bar
// endregion myregion
baz

Running region $FILE myregion will print:

bar

The same region name may be used multiple times to pull different snippets from the same file. For example, given the file:

// region provide-foo
func main() {
	fx.New(
		fx.Provide(
			NewFoo,
			// endregion provide-foo
			NewBar,
		// region provide-foo
		),
	).Run()
}

// endregion provide-foo

region $FILE provide-foo will print,

func main() {
	fx.New(
		fx.Provide(
			NewFoo,
		),
	).Run()
}

7.2 KiB Raw Blame History