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

[Docs] Cleanup docs on contributing #369

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

[Docs] Cleanup docs on contributing #369

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6c29bc0
cleanup docs on contributing
smcclure20 Jun 6, 2024
094d484
Remove
seankimkdy Jul 8, 2024
9ed70f6
Further cleanup and consolidation
seankimkdy Jul 9, 2024
197ea00
Merge branch 'main' into smcclure20/contrib-cleanup
seankimkdy Jul 9, 2024
ae415f4
Remove duplicate info
seankimkdy Jul 12, 2024
1faa8d4
Better wording for using your own GCP proj
seankimkdy Jul 12, 2024
e56f07b
Update wording about dev containers
seankimkdy Jul 12, 2024
89e48bd
Merge branch 'main' into smcclure20/contrib-cleanup
seankimkdy Jul 12, 2024
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
16 changes: 0 additions & 16 deletions docs/source/developers/contributing/prerequisites.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,22 +114,6 @@ If you'd like to persist resources after a test (i.e., not teardown project/reso
.. note::
IBM integration tests are not currently supported. We plan to add some soon.

Editor
--------------------
If you don't have a code editor set up for Go, we recommend VS Code. The experience with VS Code is high-quality and approachable for newcomers.

Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice.

- `Visual Studio Code <https://code.visualstudio.com/>`_
- `Go extension <https://marketplace.visualstudio.com/items?itemName=golang.go>`_

Launching VS Code
^^^^^^^^^^^^^^^^^^^^
The best way to launch VS Code for Go is to do *File* > *Open Folder* on the repository.

You can easily do this from the command shell with ``code .``, which opens the current directory as a folder in VS Code.


Using the Dev Container
Copy link
Collaborator

@divega divega Jun 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I am not sure it's that great to remove the editor section completely. Someone new on one or more dimensions (new to Go, or new VS Code) could find this information useful. I would probably just make it a single paragraph like:

Suggested change
Using the Dev Container
Editor
--------------------
You can use your favorite editor set up for Go. If you don't have one, we recommend `Visual Studio Code <https://code.visualstudio.com/>`_ with its `Go extension <https://marketplace.visualstudio.com/items?itemName=golang.go>`_.
Using the Dev Container

------------------------
Dev Containers allow you to run a development environment using VS Code inside a container. If you want to try this:
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Is it still valuable to at least have the pre-reqs for the dev container? Or is it explained enough in what you link above?

Copy link
Collaborator

Choose a reason for hiding this comment

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

The link is the official VS Code guideline, but I think you're right in that this short statement would be helpful as dev containers are not expected knowledge. I updated the wording under "VS Code Setup".

Expand Down
9 changes: 0 additions & 9 deletions docs/source/developers/contributing/writing-go.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,6 @@ If there's any question about how to style a piece of code, following the style
We also *mostly* agree with `Google's Go Style Guide <https://google.github.io/styleguide/go/>`_, but don't follow it strictly or enforce everything written there.
If you're new to working on a Go project, this is a great read that will get you thinking critically about the small decisions you will make when writing Go code.

Documentation
^^^^^^^^^^^^^^^^^^^^
One thing we do require is `godoc comments <https://tip.golang.org/doc/comment>`_ on **exported** packages, types, variables, constants, and functions. We like this because it has two good effects:

- Encourages you to minimize the exported surface-area, thus simplifying the design.
- Requires you to document clearly the purpose code you expect other parts of the codebase to call.

Right now we don't have automated enforcement of this rule, so expect it to come up in code review if you forget.

Linting
^^^^^^^^^^^^^^^^^^^^
We run `golint-ci <https://github.com/golangci/golangci-lint>`_ as part of the pull-request process for static analysis.
Expand Down