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.

[matthew wall]

thanks greg.

DEV_NOTES.txt still contains a *lot* more than just the release process, including baseline dependencies, gpg-specific stuff, packaging quirks for different operating systems, requirements for building docs.

DEV_NOTES.txt (how to release, pre-reqs, packaging, code stats, etc) is completely different content than devnotes.md (stuff you should know if you want to write weewx code), so the file naming is unfortunate.

agree that TODO and ROADMAP should be consolidated. issues really track the TODO items. tom tends to move on those at a much faster pace than i am able, so i sometimes go to do weewx stuff only to find the TODO items or issues are gone/closed.

i am inclined to keep developer notes (DEV_NOTES.txt content) separate from the docs, but that is just my old-skool notion that i should be able to read everything i need to build/develop without having to install a toolchain to build the docs i am supposed to read.

m

[Greg Troxel]

matthew wall <mwall...@gmail.com> writes:

> DEV_NOTES.txt still contains a *lot* more than just the release process, including baseline dependencies, gpg-specific stuff, packaging quirks for different operating systems, requirements for building docs.
>
> DEV_NOTES.txt (how to release, pre-reqs, packaging, code stats, etc) is completely different content than devnotes.md (stuff you should know if you want to write weewx code), so the file naming is unfortunate.
>
> agree that TODO and ROADMAP should be consolidated. issues really
> track the TODO items. tom tends to move on those at a much faster pace
> than i am able, so i sometimes go to do weewx stuff only to find the
> TODO items or issues are gone/closed.

I am guessing that you or Tom would feel comfortable doing these
rototills without a lot of effort; for others the effort would be mostly
making sure not to say anything wrong without the benefit of having it
all paged in.

> i am inclined to keep developer notes (DEV_NOTES.txt content) separate
> from the docs, but that is just my old-skool notion that i should be
> able to read everything i need to build/develop without having to
> install a toolchain to build the docs i am supposed to read.

My own view is that

- release process steps should really be scripted, but if not the docs
belong in the git repo as nerd-readable text

- in the git repo, easily discoverable from top-level, as
nerd-readable text, there should be an explanation of branches,
building instructions including prereqs, and information about
contributing changes. I don't much care how that's organized as
long as someone who checks out the repo and starts to look at it
finds it all quickly.

- I expected docs_src to be documentation about the program, rather
than the meta-level docs about branches, how to contribute, etc.
Sort of the man page that goes with the program built from the
source in the repo, for some value of "man page".

But indeed, I'm old-school too. I had to get an extra big backpack to
bring my RK05 back and forth :-) But seriously, I did walk to school
with a DECtape in my pocket.