all: update documentation
README.md, CONTRIBUTING.md, doc/design.md and doc/frontend.md are
updated improve clarity on the project direction and how to contribute
to the project.
Change-Id: Ia4b7302cf4851c0f777f8b7c3fa45c60dad7d989
Reviewed-on: https://team-review.git.corp.google.com/c/golang/discovery/+/766270
CI-Result: Cloud Build <devtools-proctor-result-processor@system.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 87d96b3..3d1061c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,25 +1,22 @@
# Contributing to pkg.go.dev
-Pkg.go.dev is part of the Go open source project.
-
-We would love to receive your contributions!
+Pkg.go.dev is part of the Go open source project. We would love to receive your
+contributions!
Since we are actively working on the site, we ask that you
[file an issue](https://golang.org/s/discovery-feedback) and claim it before
starting to work on something. Otherwise, it is likely that we might already be
working on a fix for your issue.
-Because we are currently working on a [redesign of pkg.go.dev](/README.md#roadmap), we will not be
-accepting any contributions for
+Because we are currently working on
+[design updates to pkg.go.dev](/README.md#roadmap), we will not be accepting
+any contributions for
[issues with a UX label](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Ago.dev+label%3AUX).
-Please read the [Contribution Guidelines](https://golang.org/doc/contribute.html)
-before sending patches.
-
## Finding issues
-All issues are labeled with the [`go.dev`
-label](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Ago.dev).
+All issues are labeled with the
+[`go.dev` label](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Ago.dev).
Issues that are suitable for contributors are additionally tagged with the
[`help wanted` label](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Ago.dev+label%3A%22help+wanted%22+).
@@ -27,29 +24,24 @@
## Getting started
-1. Get the source code:
+1. Complete the steps in the
+[Go Contribution Guide](https://golang.org/doc/contribute.html).
-`$ git clone https://go.googlesource.com/pkgsite`
+2. Download the source code for x/pkgsite:
+`git clone https://go.googlesource.com/pkgsite`
-- Our canonical Git repository is located at [https://go.googlesource.com/pkgsite](https://go.googlesource.com/pkgsite). [github.com/golang/pkgsite](https://github.com/golang/pkgsite) is a mirror of that repository.
+3. Review the [design document](doc/design.md).
-2. Review the [design document](doc/design.md).
+### Running pkg.go.dev locally
-3. We deploy to the [Google Cloud Platform](https://cloud.google.com). If you
- wish to set up a similar environment, you will want to
- download and install the Google Cloud SDK at https://cloud.google.com/sdk/docs/.
+There are two ways to run pkg.go.dev locally.
-4. If you are planning to develop any feature that involves the database, you will need
- to [set up](doc/postgres.md) and [populate](doc/worker.md#populating-data-locally-using-the-worker) your local database. To run
- the frontend and server servers locally, see the documentation for the [frontend server](doc/frontend.md) and [worker server](doc/worker.md).
+1. Use a proxy service as a datasource.
-5. Depending on the feature you are working on, review the contributing guides for:
+2. Use postgres as the datasource.
-- [Frontend development](doc/frontend.md)
-- [Worker development](doc/worker.md)
-- [Database setup](doc/postgres.md)
+See [doc/frontend.md](doc/frontend.md) for details.
## Questions
-You can find us in the #tools channel on the Gophers Slack, or you can send us
-an email at go-discovery-feedback@google.com.
+You can find us in the #tools channel on the Gophers Slack.
diff --git a/README.md b/README.md
index 3bd9d7c..4968c98 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,65 @@
# Pkg.go.dev
-[Pkg.go.dev](https://pkg.go.dev) is a website for discovering and evaluting Go
-packages and modules.
+## A site for discovering Go packages
+
+Pkg.go.dev is a website for discovering and evaluating Go packages and modules.
+
+You can check it out at [https://pkg.go.dev](https://pkg.go.dev).
## Roadmap
Pkg.go.dev [launched](https://groups.google.com/g/golang-announce/c/OW8bHSryLIc)
in November 2019, and is currently under active development by the Go team.
-Our current goal is to work on addressing the
-[UX feedback](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Ago.dev+label%3AUX)
-we have received. You can expect pkg.go.dev to be slated for some design
-changes coming soon. We plan to share these designs for feedback with everyone
-once they are ready.
+Here's what we are currently working on:
-Longer term, we are working towards redirecting godoc.org traffic to
-pkg.go.dev. We want to ensure that we address users' needs in the process. Read more
-about our [next steps for pkg.go.dev](https://blog.golang.org/pkg.go.dev-2020).
-Issues related to redirecting godoc.org traffic are being tracked
-in [Go issue #39144](https://golang.org/issue/39144).
-We plan to address these issues before redirecting traffic from godoc.org to
-pkg.go.dev.
+- Design updates: We have some design changes planned for pkg.go.dev,
+ to address
+ [UX feedback](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Ago.dev+label%3AUX)
+ that we have received.
+ You can expect a more cohesive search and navigation experience coming soon.
+ We plan to share these designs for feedback once they are ready.
-We encourage everyone to begin using pkg.go.dev today for all of their needs
-and [file feedback](https://golang.org/s/discovery-feedback)! You can redirect
+- Godoc.org redirect: Longer term, we are working towards
+ [redirecting godoc.org traffic](https://blog.golang.org/pkg.go.dev-2020) to
+ pkg.go.dev. We know that there are features available on godoc.org that users
+ want to see on pkg.go.dev, and we want to ensure that we address these. We’ve
+ been keeping track of issues related to redirecting godoc.org traffic on
+ [Go issue #39144](https://golang.org/issue/39144).
+ These issues will be prioritized in the next few months. We also plan to
+ continue improving our license detection algorithm.
+
+- Search improvements: We’ll be improving our search experience based on
+ feedback in [Go issue #37810](https://golang.org/issue/37810),
+ to make it easier for users to find the dependencies they are looking for and
+ make better decisions around which ones to import.
+
+We encourage everyone to begin using [pkg.go.dev](https://pkg.go.dev) today for
+all of their needs and to
+[file feedback](https://golang.org/s/discovery-feedback)! You can redirect
all of your requests from godoc.org to pkg.go.dev, by clicking
-`Always use pkg.go.dev` at the top of any page on godoc.org.
-
-If you are having issues with pkg.go.dev, please first check the known issues
-before following the troubleshooting guide. If that does not give you the
-information you need, reach out to us.
+`Always use pkg.go.dev` at the top of any page on [godoc.org](https://godoc.org).
## Issues
-You can chat with us on the #tools slack channel on
-the [Gophers slack](https://invite.slack.golangbridge.org).
+If you want to report a bug or have a feature suggestion, please first check
+the [known issues](https://github.com/golang/go/labels/go.dev) to see if your
+issue is already being discussed. If an issue does not already exist, feel free
+to [file an issue](https://golang.org/s/discovery-feedback).
-If you think you have an issue that needs fixing, or a feature suggestion, then
-please make sure you follow the steps to file an issue with the right
-information to allow us to address it.
+For answers to freqently asked questions, see [go.dev](https://go.dev/about).
+
+You can also chat with us on the #tools slack channel on the
+[Gophers slack](https://invite.slack.golangbridge.org).
## Contributing
We would love your help!
-Our canonical Git repository is located
-cat [go.googlesource.com/discovery](https://go.googlesource.com/discovery).
+Our canonical Git repository is located at
+[go.googlesource.com/pkgsite](https://go.googlesource.com/pkgsite).
There is a mirror of the repository at
-[github.com/golang/discovery](https://github.com/golang/discovery).
+[github.com/golang/pkgsite](https://github.com/golang/pkgsite).
To contribute, please read our [contributing guide](CONTRIBUTING.md).
diff --git a/doc/design.md b/doc/design.md
index 2a43c37..d159a4f 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -6,8 +6,8 @@
- A _worker_ that populates the database with information about new modules.
-Both services are hosted on App Engine Standard and run Go 1.13. We use
-A Postgres database managed by [Google Cloud SQL](https://cloud.google.com/sql).
+Both services are hosted on App Engine Standard and run Go 1.13. We use a
+Postgres database managed by [Google Cloud SQL](https://cloud.google.com/sql).
## The Frontend
@@ -33,8 +33,8 @@
the module zip, it also computes the number of importers of each package.
To smooth out the work of processing new modules and to take advantage of its
-rate-limiting and retry features, the worker uses a [Google Cloud
-Tasks](https://cloud.google.com/tasks) queue to manage the list of modules to be
+rate-limiting and retry features, the worker uses a
+[Google Cloud Tasks](https://cloud.google.com/tasks) queue to manage the list of modules to be
processed. The worker adds tasks to the queue when it finds new modules in the index.
The queue pushes tasks to the worker at a fixed maximum rate.
diff --git a/doc/frontend.md b/doc/frontend.md
index c974d6a..0d68174 100644
--- a/doc/frontend.md
+++ b/doc/frontend.md
@@ -1,14 +1,15 @@
# Frontend Development
-The main program lives in `cmd/frontend`.
+The main program lives in `cmd/frontend`. The bulk of the code lives in
+`internal/frontend`.
You can run the frontend locally like so:
```
-go run cmd/frontend/main.go [-reload_templates] [-direct_proxy]
+go run cmd/frontend/main.go [-dev] [-direct_proxy]
```
-- The `-reload_templates` flag reloads templates on each page load.
+- The `-dev` flag reloads templates on each page load.
The frontend can use one of two datasources:
@@ -17,7 +18,13 @@
The `Datasource` interface implementation is available at internal/datasource.go.
-The `-direct_proxy` flag can be used to run the frontend with its datasource as
-the proxy service.
+You can use the `-direct_proxy` flag to run the frontend with its datasource as
+the proxy service. This allows you to run the frontend without setting up a
+postgres database.
-The bulk of the code lives in `internal/frontend`.
+Alternatively, you can run pkg.go.dev with a local database. See instructions
+on how to [set up](doc/postgres.md) and
+[populate](doc/worker.md#populating-data-locally-using-the-worker)
+your local database with packages of your choice.
+
+You can then run the frontend with: `go run cmd/frontend/main.go`
