Move to detailed docs generation with Hugo and Docsy

[jaypipes]

I think ghw has become sufficiently feature-rich to warrant a real docs solution other than the README.md page. I'm thinking of using Docsy for this.

[ibm-adarsh]

Hi @jaypipes ,

I realize this is a fairly old request, but I do believe adding this support would significantly enhance the user experience and help align things more closely with industry standards.

While I wouldn’t call myself an expert, I have previously worked with Hugo in my previous organization and would be happy to contribute to this effort. I’d appreciate the opportunity to collaborate with you and get your guidance along the way.

Looking forward to your thoughts.
Adarsh

[jaypipes]

Hi @ibm-adarsh ! I had actually done a good chunk of this work and pushed my work here:

https://github.com/go-hardware/www

The intention was to move ghw from the github.com/jaypipes Github Organization to the github.com/go-hardware Organization per this issue.

Unfortunately, I got sidetracked and back-burnered this effort.

However, as we head (quickly) towards a v1.0 release of ghw, I'd like to take this up again and do the transfer of Github Organizations using the following steps:

1. Transfer the github.com/jaypipes/ghw repository using the GitHub interface to the github.com/go-hardware organization. This process preserves all issues, pull requests, stars, and history.
2. Update the library's go.mod file and internal import paths to use the new organization's path (i.e. module github.com/go-hardware/ghw instead of module github.com/jaypipes/ghw).
3. Tag and publish a new release (v1.0.0) with the updated module path. This new version will use the new path, while older versions will continue to use the GitHub redirect to the old path.
4. Add a deprecation notice to the old module path in the go.mod file to inform users about the new location.

// Deprecated: use github.com/go-hardware/ghw instead.

The above steps are the recommended steps to change the Github Organization for a Go library. I will create a test repository called github.com/jaypipes/ghwtransfer that I will transfer to the github.com/go-hardware organization to verify that the above steps result in a smooth transfer...

/cc @ffromani

[jaypipes]

@ffromani @ibm-adarsh @sewnie @mmlb OK, so I spent some time yesterday testing the above procedure for transferring the ghw library from the jaypipes to the go-hardware Github Organization.

Everything worked as described, but there are the important takeaways for our users and we should decide whether this is acceptable, given we have >900 public open source repositories that import github.com/jaypipes/ghw including some big names like Wails, Tinkerbell, sriov-network-device-plugin, LocalAI, sriov-network-operator, metal-operator, node-feature-discovery, ClickHouse (operator), etc...

1. If they do not update their go.mod files to reference the v1.0.0 release version of github.com/jaypipes/ghw and do not run go get -u github.com/jaypipes/ghw, nothing breaks and the Go package referenced in their go.mod file would continue to be served from the old github.com/jaypipes/ghw location.
2. If they update their go.mod file to reference the v1.0.0 release version of github.com/jaypipes/ghw or run go get -u github.com/jaypipes/ghw, they will get the following failure:

> go get -u github.com/jaypipes/ghw          
go: github.com/jaypipes/ghw@upgrade (v1.0.0) requires github.com/jaypipes/ghw@v1.0.0: parsing go.mod:
	module declares its path as: github.com/go-hardware/ghw
	        but was required as: github.com/jaypipes/ghw

which would require the user replace the github.com/jaypipes/ghw import path with the github.com/go-hardware/ghw import path and fix up the go.mod and go.sum files manually:

# Fix all the import paths ...
find . -type f -exec sed -i 's/github.com\/jaypipes\/ghw/github.com\/go-hardware\/ghw/' {} \;
# Delete the old go.sum entries
sed -i '/github.com\/go-hardware\/ghw/d' go.sum
# Fix up the require import in go.mod
go mod edit -require=github.com/go-hardware/ghw@v1.0.0
# Finally, clean up the go.sum
go mod tidy

@ffromani do you think the benefits of moving to a "neutral" Github organization like go-hardware instead of jaypipes is worth our users needing to perform the above steps?

[ibm-adarsh]

Hi @jaypipes ,

Thanks a lot for taking the time to test this thoroughly and for documenting the exact impact, this is really helpful.

In my view, moving to a neutral organization like github.com/go-hardware is a good long-term decision. It improves project ownership clarity, reduces single-maintainer perception, and aligns well with the direction towards a stable v1.0 release as per the standards followed across industry. These benefits would likely outweigh the one-time migration effort required from users.

Also, since existing consumers will not be affected unless they explicitly upgrade, the risk of sudden breakage is quite low. For those who do upgrade, the fix steps are clear and standard for Go module path changes. We can further ease the transition by documenting this clearly in release notes and adding a short migration guide.

Additionally, we can include a clear deprecation and migration notice in the current repository’s README pointing users to the new module path and explaining the required steps. That should help minimize confusion during the transition.

Overall, I feel the move is reasonable and worth doing before the v1.0 release to avoid bigger disruption later. Happy to help with documentation or migration guidance if needed.

[jaypipes]

thanks @ibm-adarsh. I'm on the fence still and would like to hear from @ffromani whether he thinks the experience for existing users I highlight above is acceptable.

[jaypipes]

@ffromani friendly ping on this one :) definitely want your thoughts on it!