GH-39761: [Docs] Link to Go documentation references outdated documentation from 2018 by gtomitsuka · Pull Request #39750 · apache/arrow

gtomitsuka · 2024-01-22T19:42:20Z

Rationale for this change

The godoc format shows docs in a versioned fashion, making the "basic" link reference v0.0.0 from 2018, and godoc doesn't warn you when docs are outdated. Accordingly, for people to find "real" documentation, they have to manually search for the latest docs.

Otherwise, it gives the impression that the package is abandoned / makes devs waste considerable time — e.g., I work with Go professionally and wasted 15 minutes on the 2018 docs until I realized they were wrong.

What changes are included in this PR?

Reference the latest version (v16) in the list of supported implementations of the Arrow website & R package.
Add step to release process that automatically updates the version on release

Are these changes tested?

Yes, I've added tests for this to dev/release/post-11-bump-versions-test.rb.

Are there any user-facing changes?

Yes, the link to Implementations > Go on the website will change.

Closes: [Docs] Link to Go documentation references outdated documentation from 2018 #39761

Current link references old v1 implementation from 2018 (out-of-date), confusing people on Arrow for Go's capabilities

kou · 2024-01-22T21:48:48Z

If we specify a version statically, we need to update it periodically.
Can we use a URL that refers the latest version?

gtomitsuka · 2024-01-22T22:03:29Z

I've researched this and haven't found any way to tag a version as latest on godoc; I checked the codebase it seems that the team is already aware of this issue and uses the static link to arrow/v16 on arrow/go/README.md, I wasn't sure which version to use as only v15 is tagged but switching to v16 for consistency

kou · 2024-01-23T00:25:30Z

We substitute it in our release process:

arrow/dev/release/utils-prepare.sh

Lines 152 to 165 in c9ca62a

    
           pushd "${ARROW_DIR}/go" 
        
           find . "(" -name "*.go*" -o -name "go.mod" -o -name README.md ")" -exec sed -i.bak -E -e \ 
        
             "s|(github\\.com/apache/arrow/go)/v[0-9]+|\1/v${major_version}|g" {} \; 
        
           # update parquet writer version 
        
           sed -i.bak -E -e \ 
        
             "s/\"parquet-go version .+\"/\"parquet-go version ${version}\"/" \ 
        
             parquet/writer_properties.go 
        
           sed -i.bak -E -e \ 
        
             "s/const PkgVersion = \".*/const PkgVersion = \"${version}\"/" \ 
        
             arrow/doc.go 
        
           find . -name "*.bak" -exec rm {} \; 
        
           git add . 
        
           popd

If we need it, could you open a new issue (this is not a MINOR fix https://github.com/apache/arrow/blob/main/CONTRIBUTING.md#Minor-Fixes ) and use the same approach in this PR?

gtomitsuka · 2024-01-23T11:25:33Z

Yep, will do

github-actions · 2024-01-23T11:32:44Z

⚠️ GitHub issue #39761 has been automatically assigned in GitHub to PR creator.

…rocess

gtomitsuka · 2024-01-23T11:59:05Z

Should be fixed now

zeroshade

this LGTM once the failing dev tests are fixed. Most likely the new diffs need to be added to dev/release/post-11-bump-versions-test.rb as expected diffs

gtomitsuka · 2024-01-23T20:30:39Z

Thanks for pointing me in the right direction! I updated dev/release/post-11-bump-versions-test.rb, the tests should pass now

dev/release/utils-prepare.sh

dev/release/post-11-bump-versions-test.rb

gtomitsuka · 2024-01-24T07:24:33Z

Thanks for the review! I applied all requested changes.

kou

+1

Thanks!

conbench-apache-arrow · 2024-01-24T16:43:14Z

After merging your PR, Conbench analyzed the 4 benchmarking runs that have been run so far on merge-commit 2e8bd8d.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details.

…ocumentation from 2018 (apache#39750) ### Rationale for this change The godoc format shows docs in a versioned fashion, making the ["basic" link](https://pkg.go.dev/github.com/apache/arrow/go) reference v0.0.0 from 2018, and godoc doesn't warn you when docs are outdated. Accordingly, for people to find "real" documentation, they have to manually search for the latest docs. Otherwise, it gives the impression that the package is abandoned / makes devs waste considerable time — e.g., I work with Go professionally and wasted 15 minutes on the 2018 docs until I realized they were wrong. ### What changes are included in this PR? * Reference the latest version (v16) in the list of supported implementations of the Arrow website & R package. * Add step to release process that automatically updates the version on release ### Are these changes tested? Yes, I've added tests for this to `dev/release/post-11-bump-versions-test.rb`. ### Are there any user-facing changes? Yes, the link to Implementations > Go on the website will change. * Closes: apache#39761 Authored-by: Gabriel Tomitsuka <g@gtomitsuka.com> Signed-off-by: Sutou Kouhei <kou@clear-code.com>

…tation from 2018 (#39750) ### Rationale for this change The godoc format shows docs in a versioned fashion, making the ["basic" link](https://pkg.go.dev/github.com/apache/arrow/go) reference v0.0.0 from 2018, and godoc doesn't warn you when docs are outdated. Accordingly, for people to find "real" documentation, they have to manually search for the latest docs. Otherwise, it gives the impression that the package is abandoned / makes devs waste considerable time — e.g., I work with Go professionally and wasted 15 minutes on the 2018 docs until I realized they were wrong. ### What changes are included in this PR? * Reference the latest version (v16) in the list of supported implementations of the Arrow website & R package. * Add step to release process that automatically updates the version on release ### Are these changes tested? Yes, I've added tests for this to `dev/release/post-11-bump-versions-test.rb`. ### Are there any user-facing changes? Yes, the link to Implementations > Go on the website will change. * Closes: #39761 Authored-by: Gabriel Tomitsuka <g@gtomitsuka.com> Signed-off-by: Sutou Kouhei <kou@clear-code.com>

Fix link to Go documentation

b032a88

Current link references old v1 implementation from 2018 (out-of-date), confusing people on Arrow for Go's capabilities

github-actions bot added Component: Documentation awaiting review Awaiting review labels Jan 22, 2024

gtomitsuka changed the title ~~MINOR: [DOCS] Link to Go documentation references outdated documentation from 2018~~ MINOR: [Docs] Link to Go documentation references outdated documentation from 2018 Jan 22, 2024

Update reference to Go implementation in _pkgdown.yml

e206501

gtomitsuka requested review from paleolimbot and thisisnic as code owners January 22, 2024 19:50

github-actions bot added the Component: R label Jan 22, 2024

Bump versions to match go/README.md

4728eff

gtomitsuka mentioned this pull request Jan 23, 2024

[Docs] Link to Go documentation references outdated documentation from 2018 #39761

Closed

gtomitsuka marked this pull request as draft January 23, 2024 11:31

gtomitsuka changed the title ~~MINOR: [Docs] Link to Go documentation references outdated documentation from 2018~~ GH-39761: [Docs] Link to Go documentation references outdated documentation from 2018 Jan 23, 2024

gtomitsuka added 3 commits January 23, 2024 12:47

Update reference to godoc on version release

bb86eed

Merge branch 'apache:main' into patch-1

313e339

Update godoc version reference in r/_pkgdown.yml as part of release p…

80ae51c

…rocess

gtomitsuka marked this pull request as ready for review January 23, 2024 11:58

gtomitsuka requested review from assignUser, kou and raulcd as code owners January 23, 2024 11:58

zeroshade approved these changes Jan 23, 2024

View reviewed changes

github-actions bot added awaiting merge Awaiting merge and removed awaiting review Awaiting review labels Jan 23, 2024

Test godoc link changes

b1d0367

kou reviewed Jan 23, 2024

View reviewed changes

dev/release/utils-prepare.sh Outdated Show resolved Hide resolved

dev/release/utils-prepare.sh Outdated Show resolved Hide resolved

dev/release/utils-prepare.sh Outdated Show resolved Hide resolved

dev/release/utils-prepare.sh Show resolved Hide resolved

github-actions bot added awaiting changes Awaiting changes and removed awaiting merge Awaiting merge labels Jan 23, 2024

kou reviewed Jan 24, 2024

View reviewed changes

dev/release/post-11-bump-versions-test.rb Show resolved Hide resolved

dev/release/post-11-bump-versions-test.rb Show resolved Hide resolved

apply changes from code review

d70320f

github-actions bot added awaiting change review Awaiting change review and removed awaiting changes Awaiting changes labels Jan 24, 2024

kou approved these changes Jan 24, 2024

View reviewed changes

kou merged commit 2e8bd8d into apache:main Jan 24, 2024

kou removed the awaiting change review Awaiting change review label Jan 24, 2024

github-actions bot added the awaiting merge Awaiting merge label Jan 24, 2024

Conversation

gtomitsuka commented Jan 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rationale for this change

What changes are included in this PR?

Are these changes tested?

Are there any user-facing changes?

Uh oh!

kou commented Jan 22, 2024

Uh oh!

gtomitsuka commented Jan 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kou commented Jan 23, 2024

Uh oh!

gtomitsuka commented Jan 23, 2024

Uh oh!

github-actions bot commented Jan 23, 2024

Uh oh!

gtomitsuka commented Jan 23, 2024

Uh oh!

zeroshade left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gtomitsuka commented Jan 23, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gtomitsuka commented Jan 24, 2024

Uh oh!

kou left a comment

Choose a reason for hiding this comment

Uh oh!

conbench-apache-arrow bot commented Jan 24, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gtomitsuka commented Jan 22, 2024 •

edited

Loading

gtomitsuka commented Jan 22, 2024 •

edited

Loading

zeroshade left a comment •

edited

Loading