DEV_NOTES and dev_notes, branch naming: confusing

[Greg Troxel]

My weewx install is running fine, but I'm updating from python 3.12 to
3.13 and figured I'd upgrade along the production branch. (I'm not
asking for help with this.) I'm used to writing code, to git, and to
doing things on branching and merging. I'm not particularly good at
remembering how each of N projects names branches and does things :-)

This is sort of a trip report from unconfusing myself and some related
comments.

I quickly realized that there was 'develop' and 'master', and guessed
that master means "release branch for whatever is the release this
minute" and develop means "what master would mean if release branches
were named with release versions, e.g. weewx-5 or weewx-5.2" :-) But I
wasn't 100% sure and thought I'd read the docs.

In README.md, I found nothing useful about dealing with the code, as is the
github custom :-) I read the other files, and noticed

ROADMAP.md, TODO.md: These are sort of the same but not really, and it
would be nice if someone merged them into just TODO.md, and perhaps
explained how they relate or don't relate to enhancement tickets.

DEV_NOTES.txt: This should be called RELEASE-PROCEDURE.md. It's not
about how to change the code or how to contribute to the project

I was about to conclude that the branch structure wasn't documented and
write that here, but then I looked in docs_src, which I expected to be
about user-facing docs. It mostly is, but there is devnotes.md, which
contains information both about the code and about dealing with github.

I suggest that docs_src.txt be moved to top-level and split into:

ARCHITECTURE.md: describe the codebase
CONTRIBUTING.md: describe branch naming and how to contribute

[Tom Keffer]

Thanks, Greg. These are useful, constructive comments.

In defense, the document Notes for developers is on the front page of the documentation!

But I take your point about misleading names and about how critical development information is in unpredictable locations.

-tk

--
You received this message because you are subscribed to the Google Groups "weewx-development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to weewx-developm...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/weewx-development/rmizf7c4s3o.fsf%40s1.lexort.com.

[Vince Skahan]

Greg - FWIW - I interpret the branch names more along the lines of:

* master - what likely will be in the 'next' release with some certainty

* development - what future releases are being developed from, which might be more/less/different than 'master'

* For past releases I use the tags ala https://github.com/weewx/weewx/tree/v5.2.0 to get the source tree that version was built from

Thankfully, weewx doesn't use the full-blown github workflow with 'release' and feature branches and the like.  Those can get crazy complicated mechanically.

You probably will see changes made to 'master' that didn't flow through 'development' first, meaning a back-merge master=>development happens occasionally, which would never happen in a strict gitflow process.  It's unfortunately pretty easy in the github interface to do a PR that merges to the wrong destination tree (ie, to master, when I should have done the PR toward development).  I know I mess that up too frequently.