proj-oot-ootDevelopmentProcessNotes2

terminal adds upon package install sound like a great idea to me! we should allow them, unlike npm:

https://www.zdnet.com/article/npm-bans-terminal-ads/

---

[1] lists 4 kinds of docs:

tutorial explanatory how-to/recipe reference

[2] adds

README

i would also add

things like Python's tutorial, or the Ruby book,

which are mixtures of tutorial and explanatory, while also being comprehensive (to a point)

--- license

" I have talked to GCC developers about integrating a Rust frontend and they said, the main blocker is the fact that the language specification isn't stable and a fast moving target. ... I think the instability the GCC devs are concerned about is the release schedule. Rust has 9 releases per year while GCC has 4-5 releases. Unless you update your compiler quickly, you won't be able to use much of the crates.io ecosystem as crates are quick at requiring a new compiler version. Often the implementation of a new language feature is still getting last-minute fixes up to 6 weeks before the release, and sometimes even after that beta period. ... GCC can't miss out releases. The rustc 1.36.0 frontend needs at least a 1.35.0 frontend to compile itself. And most Rust programs in the ecosystem work with rustcs compiled with older LLVM releases, but most Rust programs that have dependencies do need newer rustc releases.

... As for stability of MIR: currently I think MIR is serialized to disk in a glorified mmap way. Basically following the Rust memory representation. It's great if both the creator of the MIR as well as the part that reads the MIR are written in Rust. Furthermore, there are libraries about how memory layout should look like that are provided to codegen backends. Those libraries are written in Rust and not really usable outside of Rust. So currently unless someone serializes MIR using e.g. bincode and provides C bindings for those layout libraries, there are good reasons to write the codegen backend in Rust itself, at least the part that translates MIR to the next stage. "

---

There's an organization called Blue Oak Council in which 3 FOSS lawyers work on licensing-ish stuff:

https://heathermeeker.com/2019/03/07/blue-oak-council-and-the-permissive-license-list/

Kyle Mitchell (executive director), Heather Meeker, Luis Villa. Kyle authors a zillion new licenses, so i'd like to see that this stuff was actually supported by the others, and it seems it was. According to that post by Heather all actively participated in the license list project and in the creation of the Blue Oak license.

Luis also publicly supports this work: " Luis Villa argues that the list of OSI-approved licenses isn't a comprehensive list of usable open source licenses. It should therefore be avoided in contracts or license clauses. But if not that, what is the purpose of the list? Would it make sense to create a smaller list of useful licenses? Villa points to his Blue Oak project as a list of useful permissive licenses. " -- [3]

"I'd happily submit the Blue Oak Model permissive license as an initial guinea pig for such a process...I have no current plans to submit the license primarily because I am too busy to have a massively inefficient discussion on license-review" -- http://lists.opensource.org/pipermail/license-discuss_lists.opensource.org/2019-March/020279.html

"Agree there definitely doesn’t need to be a flood of new licenses, of course, but the correct number is > 0 (or we should nuke everything other than Apache. Or Blue Oak Winking face)" -- https://twitter.com/luis_in_brief/status/1215503399648514048

"(I should disclose here that Kyle and I work together quite a bit, and I co-authored a license with him in 2019—the Blue Oak Model License—that I volunteered to submit to the OSI as a guinea pig to test any improved processes.)" -- https://blog.tidelift.com/open-source-licenses-2019-year-in-review

Luis Villa is the Apache 2.0 guy, i think.

Richard Fontana seems to like the Blue Oak License too: "Blue Oak is, as to its content, both extremely simple and extremely non-controversial" -- Richard Fontana (Mar 19 2019)

however earlier here he says:

"new putative FOSS licenses should be drafted in public and collaboratively, not in private as I gather Blue Oak was" (https://twitter.com/richardfontana/status/1104811186665721856) and mentions that here: https://lists.fedorahosted.org/archives/list/copyleft-next@lists.fedorahosted.org/thread/2YJ4COON2V33J7SF7B2DXE3EYUHVZXWA/ (Mar 16 2019)

The group of Meeker, Villa, Mitchell also works on the Polyform Project, a set of non-FOSS licenses: https://polyformproject.org/licenses/

" A group of attorneys also published a set of standard, but again very explicitly commercial/not-open, licenses as the Polyform Project.

While the lawyers involved in these (including Kyle, Heather Meeker, and me) would be the first to tell you that these licenses aren’t open source, I include them here because they bear two key similarities to open source licenses. " -- https://blog.tidelift.com/open-source-licenses-2019-year-in-review

and Villa claims that Mitchell's non-FOSS "License Zero" has some adoption [4]

https://licensezero.com/ (seems like the actual license is Parity) related forum: https://forum.artlessdevices.com/top

Villa is a little chillier towards other licenses there:

" Commercial “open source”

In late 2018, Mongo submitted the Server Side Public License to the OSI, intended to replace the AGPL with a license that was more aggressive and protected their business from cloud vendors. In 2019, this trend accelerated and turned into a movement of a sort, with Redis using a new source available license. These discussions eventually snowballed into something calling itself Commercial Open Source Software, centered around an Open Core Summit.

The entire thing was a little odd, given that open source has (from literally the time the phrase was coined!) been pro-commerce, and that also since the nominally pro-commerce COSS folks appeared to be arguing primarily for licenses that...oppose commercial use.

While I think some of the readings of this have been uncharitable, suffice to say that this messaging has been at best very confusing and at worst perceived as an active attack on the definition of open source by venture capitalists who want Red Hat-like returns without putting in the effort.

Regardless of the confused messaging, I expect we’ll see more of this in 2020—in both good and bad faith. "

The rest of the post speaks somewhat admiringly about CAL (a broader-than-GPL license that extends freedom to data as well as code) and Parity (another extremely broad license, but one with simplified wording; from Mitchell). These are noted on Blue Oak's copyleft guide: https://blueoakcouncil.org/copyleft

interestingly Blue Oak Council also has a model FOSS usage policy for use by businesses. Cool! https://blueoakcouncil.org/starter-policy for small companies and https://blueoakcouncil.org/company-policy for larger ones. And here's a policy for contractors: https://blueoakcouncil.org/development-use

here's a blog post about how blue oak council came to be: https://writing.kemitchell.com/2019/03/07/Blue-Oak-Council.html

interestingly Bruce Perens has split from OSI:

https://news.slashdot.org/story/20/01/05/208249/open-source-initiative-co-founder-bruce-perens-resigns-citing-move-toward-license-that-isnt-freedom-respecting#perens_coherent

and he now advocates for everyone to use one of AGPL 3, LGPL3, or Apache 2, to reduce confusion.

github suggests GPLv3 and MIT: https://choosealicense.com/ but also is cool with AGPLv3, Apache 2.0, MIT: https://choosealicense.com/licenses/

GNU suggests Apache 2.0 for permissive: https://www.gnu.org/licenses/license-recommendations.html

here's mitchell's take on a minimal set of licenses: https://writing.kemitchell.com/2019/03/17/License-Utopia.html

" Stephen Paul Weber occasionally sees such “any OSI-approved license” terms in contests or in aggregators. Sometimes, any OSI- or FSF-approved license is allowed, to avoid choosing “sides”. Fontana thinks that approach is clever: both OSI and FSF are respected neutral authorities, unlike e.g. Blue Oak or Fedora. As a historical point, Fontana remembers that Fedora did not rely on the OSI license list because OSI was then seen as too commercially influenced. Nowadays, OSI criticism seems to be the opposite. Henrik Ingo thinks the OSI is now much more important than back then, because Linux distros no longer have the role of kingmakers: whether the software is packaged for Debian or Fedora is no longer crucial for an open source project. "

here's the FSF list:

https://www.gnu.org/licenses/license-list.en.html

here's the OSI list:

https://opensource.org/licenses

https://www.kiuwan.com/blog/comparison-popular-open-source-licenses/ says that whitesource says that the most popular permissive licenses are MIT and Apache 2.0

here's a License Picker on Meeker's website:

https://heathermeeker.com/license-picker-2-0/

here's wikipedia's comparison page:

https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licences

here's blue oak's permissive license:

https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licences

here's blue oak's permissive license list:

https://blueoakcouncil.org/list

the only 'Gold' rated license is BSD-2-Clause Plus Patent License (BSD-2-Clause-Patent) (and it looks like they consider their own license Gold or better than Gold). Apache 2.0, MIT are both rated 'silver'.

afaict BSD-2-Clause-Patent isn't well known and isn't even on FSF's list at https://www.gnu.org/licenses/license-list.en.html.

https://spdx.org/licenses/BSD-2-Clause-Patent.html https://opensource.org/licenses/BSDplusPatent https://opensource.org/licenses/BSDplusPatent links to :

GNU License List Wikipedia License List OSSWatch License Diff Choose a license (by Github)

here's some discussion on Blue Oak (Mitchell thinks it's better than MIT and BSD): https://writing.kemitchell.com/2019/03/09/Deprecation-Notice.html https://blueoakcouncil.org/2019/03/06/model.html https://news.ycombinator.com/item?id=19347898

Mitchell seems to think that Blue Oak is the plain language version of Apache, at least in some respects: "Licenses like Apache 2.0 show how lawyers do this in legal terms for private deals every day. Blue Oak shows the same job done in everyday English, without long lists, run-on sentences, or complex scope rules." That blog post is generally complimentary of Apache 2.0, except that he thinks the rules around contributors are too complex.

here's something else he says about apache 2.0:

 kemitchell on Mar 10, 2019 [–]

Both Blue Oak and Apache are relatively modern permissive licenses, but they differ intentionally in design. In the short to medium term, I foresee that many projects will continue to choose Apache where contributions from large software patent holders are essential, because of Apache's complex rules on patent scope. At the same time, I think large software patent holders will prefer to receive code under the uncomplicated Blue Oak patent grant, even as they insist on Apache's mazelike compromise for outbound contributions. -- https://news.ycombinator.com/item?id=19347898

so my summary:

• i really like the Blue Oak model permissive license because it's so readable: https://blueoakcouncil.org/license/1.0.0
• and it has at least 3 attorney's assent -- and i've heard of Villa before
• but its not certified by OSI, FSF (it is listed on SPDX but i think that's just a list, not an approval)
• but Apache 2.0 is certainly more widely known. I wonder why it only rated a Silver instead of a Gold. Maybe because https://blueoakcouncil.org/2019/03/06/model.html says they don't like "licenses with defensive termination provisions"? I like those, but hey, i agree it's simpler and maybe less scary for corporate users' lawyers if the license doesn't have those. That blog post says that Blue Oak license is "shorter, simpler, and more permissive than Apache 2.0."
• mb just dual license, etc
• or mb submit it to FSF or OSI. Only a 'license steward' can submit to OSI. FSF doesn't really invite submission and suggests that you just use an existing license.

---

user 'skade' on lobsters volunteers to be contacted by and give advice to programming language community organizers, is particulary happy to give advice on conference organization and on surveys:

https://lobste.rs/s/xgquet/2020_state_haskell_survey#c_hp7nfs

---

regarding PL community surveys, user 'skade' on lobsters suggests starting by copying the battle-tested survey from Rust.

An example of some tricky stuff he gives is that rather than asking about trans-ness, for various reasons it may be better to just ask:

    “Do you consider yourself a member of an underrepresented demographic in technology?”
        I won’t list them all here, but it lists 14 characteristics that we are aware of, such as gender identity, race, but also language skill + a free form field
    “Do you feel your situation makes it difficult for you to participate in the Rust community?”
        Yes
        No
        Maybe

---

some more ideas for release methodology:

• git's master/next/seen/maint/topicbranch ('gitworkflows')
• linux's signed-off, acked-by/reviewed-by, lieutenant/subsystem repos, subsystem-otm trees, maint releases
• progression thru dev, alpha, beta repos (my old release staging workflow)
• git-flow

some excerpts from my old 'release staging' workflow:

"

• dev: the latest version checked-in to the dev repo
• alpha: a release approved by the dev team
• preview: a closed-beta release approved by the QA team
• beta: an open-beta release
• production: for public use

Project roles

• Lead: the lead has the final say on what goes into each alpha release, and when it is ready.
• Core committers: people who have commit access to the testing repo
• Contributors: Everyone else.

Releases owned by dev

• dev: All commits to the central dev repo should pass the automated tests and should have gone through InitialCodeReview?. To doublecheck, whenever there is a commit to the central dev repo, the Hudson server runs a battery of tests on it. If it passes those tests, it is automatically deployed to "dev".
• ffreeze (feature freeze): When the dev team decides, and when there is currently no other release making its way through testing, the current version of the dev repo is tagged with a version number and cloned into a release branch.
• alpha: The pre-alpha version is then further improved..When the dev team decides, they tag the current revision of the testing repo and deem it an "alpha" release (see AlphaReleaseCriteria?).

Releases owned by QA/ops

• preview: The alpha release is used internally and tested by the QA team, and bugs found are fixed by developers. New bugfixed alpha releases are built from the stable repo. When the QA team deems it ready, the contents of the stable repo becomes a "preview" release... Bugs continue to be fixed in the "testing" repo.
• beta: When the QA team deems it ready, the contents of the "testing" repo becomes a "beta" release. This is much like a preview release, except that anyone can use it.
• production: When the QA team deems it ready, the "testing" repo is renamed to "stable" (and the previous "stable" repo is archived), and its contents are deployed to "production". This is the release that we recommend for general use.

Note that, until the previous version has made its way through preview and beta and is deployed to production, another alpha release won't be made.

Git Repositories

We will be using the git-flow workflow. Most of this page needs to be updated to be consistent with that terminology.

Following the git-flow branching model, we have three active git branches at any one time for each project:

• develop: where new features are developed
• release (one for each release; doesn't exist yet): a branch for a version that is currently in alpha, preview, or beta
• master: a repo for the version that is currently deployed in production

The develop branch keeps on growing. When a ffreeze release is made, the dev repo is branched into a release branch. When the version in the release branch is deemed stable enough for production, the release branch is merged into "master".

In addition, developers are encouraged to maintain OtherRepos? for personal development and/or for developing features which do not yet qualify for acceptance into dev. Please see the page OtherRepos? for a list of these.

Versions

We will use dotted version identifiers with 3 numbers. The first numbers is the major version number (used to signify a substantial overhaul of code or additional functionality), the second is the minor version number (incremented each time a feature freeze is instituted, and the develop branch is branched into a new release branch), and the third is the revision number (incremented most times that a new alpha, preview, beta, or production version is deployed).

These internal version numbers are not the same as the public API version numbers.

Example

For example, development will begin in the "develop" branch until the dev team deems it time for a feature freeze, at which time the current version will be tagged in the develop branch as version 0.0.0. It will be branched into a release branch named 0.0.

In the release branch, the feature frozen version will be improved until the dev team deems it ready for alpha. These changes will generally be merged into the develop branch also.

When it is time to make an alpha the current version of the release branch will be tagged (presumably as 0.0.1), and also tagged as "alpha". The alpha version will be used internally. It will be improved until it is deemed ready for "preview" (closed beta), at which point it will be tagged with a version number, perhaps 0.0.2, and also with "preview". Then it will be offered to outside preview testers. At some point it will be deemed ready for "beta" (open beta), tagged with a version number, perhaps 0.0.3, and "beta". Then it will be offered to anyone who wants to try it out. At some point it will be deemed ready for "production", tagged with a version number, perhaps 0.0.4, and "production". At this point it will be merged into the branch "master".

Hopefully there will rarely need to be changes made to the branch "master" aside from merging in new release branches. Such changes will be made on so-called "hotfix" branches. "Hotfix" branches will be merged into the develop branch also.

While version 0.0.x is making its way through the release branch on its way to master, additional features may be being developed in the develop branch. These are being targeted at future alpha release 0.1.0. When a production release is released (i.e. when a release branch is merged into master), the dev team will try to make another feature freeze as soon as feasible, at which point the current contents of the develop branch will be tagged as 0.1.0 and branched into a new release branch, and the process will repeat.

Note that every release is associated with an increment of the revision number, and the minor version number is incremented when a feature freeze takes place and the contents of the develop branch is branched into a release branch. The major version number is subjective.

Demo and sandbox: other repos/version identifiers for special purposes

"

---

ok so my current synthesis/best guess for release methodology:

version numbers: marketing, break, normal, hotfix

prerelease tags: -next, -alpha, -preview, -beta, -rcN

• next: current state of the next release. Always builds, passes active automated tests. All code has been reviewed and signed-off by code owners/lieutenants.
• alpha: developers should be using this to test it. Feature frozen.
• preview: closed beta (only invited users should be using this to test it). Otherwise like beta.
• beta: open beta (adventurous users should be using this to test it). Must have been alpha tested. No known blocking bugs.
• rcN: release candidate #N. Must have been beta tested.

repos: dev, next, testing, stable - dev: 'committers' have access to this. There may be branches for issues, features, and lieutenants. The point of this branch is for all of the committers to be able to show their work to each other and merge their work into each others'. There is a 'master' branch which is only writable by the tech lead. Merge commits may be used within this repo. The 'master' branch is always based on the head 'next' version but otherwise may have history rewritten. Any version number tags in this repo should have a prerelease suffix, which should be other than 'next/alpha/preview/beta/rcN'. The 'master' branch should always build but otherwise may have not work. The 'master' branch is a throw-away integration branch; work should not be based on it. - next: only tech lead (or whoever has the final signoff on development) has access to this. The 'master' branch is the only one defined by this workflow; any version number tags have the staging tag '-next'. This branch has a linear history (rebase and then fast-forward merges only), however this history is rebased on stable after each release. When the testing repo is unoccupied and the tech lead wishes, they tag a version '-alpha', and cloned into the 'testing' repo. - testing: only the stable maintainer and the tech lead have access to this. An 'alpha' version is cloned from the 'next' repo and eventually contain versions progressing thru tags '-alpha', (possibly '-preview'), '-beta', '-rcN'. The 'master' branch is the only one defined by this workflow. This branch has a linear history. A release is merged from this repo into 'stable'. - stable: only the stable maintainer and the tech lead have access to this. A release is fast-forward merged from the 'testing' repo into the 'master' branch of stable. This branch has a linear history. If bugfixes/hotfixes are required to old releases, a bugfix branch is made from the release.

approval dispositions:

• reviewed-by: a reviewer approved of it
• signed-off: a lieutenant or code owner signed off

roles:

• reviewer: someone with the power to review code
• committer: someone with commit access to the dev repo
• lieutenant or code owner: A committer to whom the tech lead looks to to approve changes in certain topics or files (via signoffs). Lieutenants/code owners may not want to look at code until after it has been reviewed by someone else.
• project lead: in charge of what gets released (in charge of 'next' and marking things alpha, preview, beta, rcN)
• stable maintainer: in charge of bugfix releases, and probably has a veto on what gets released and what gets marked preview, beta, rcN

Workflow:

• development happens in 'dev'. Each 'lieutenant' has a personal branch in 'dev' and there are also topic branches in 'dev'. This repo exists to publicize work that committers think is ready for others to pull/merge. Work in 'dev' should be based on either on 'stable/master', or on 'next/master'. Pull requests are made by lieutenants to the project lead to merge work into 'next' (after rebasing on 'next').
• dev/master is a throw-away integration branch to test out merging the various other work in 'dev'. Other work in 'dev' should not be based on it.
• project lead accepts fast-forward merges from 'dev' into 'next'
• when the testing repo is unoccupied, and the project lead feels that it's time to push out a new version, they tag the head version in next/master with 'x.y.z.0-alpha', and clone it into the 'testing' repo. After this they can continue new feature development in 'next' in parallel with feature-frozen development in 'testing'.
• when the stable maintainer believes that a version in the testing repo has met the criteria for a preview/beta/rc release, they tag it as such
• when the stable maintainer believes that a release candidate has met the criteria for a release, they tag it with the release version number (without a prerelease tag) and merge it into stable/master (at this point the testing repo is considered unoccupied again).
• the project lead then rebases/rebuilds 'next/master' based upon the new release at the head of stable/master
• if bugfixes/hotfixes are required to old releases, a bugfix branch is made from the release in the 'stable' repo. The fourth version number is incremented. Typically bugfixes should also be applied to testing and to next

Analogies to other workflows:

• git flow: next/master is like git flow's develop, testing/master is like git flow's release branches, bigfix branches are like git flow's hotfix branches, and stable/master is like git flow's master
• Linux kernel workflow: next, testing, stable are like Linus's tree. Branches in dev are linux's lieutenant's trees. dev/master is like the linux 'next' tree
• Gitworkflow: next is like gitworkflow's next, dev/master is like gitworkflow's seen, the union of testing and stable is like gitworkflow's master except that Gitworkflow merges hotfixes into master too, stable bugfix branches are like maint branches

Note: if you prefer branches to repos, then 'stable/master' could just be the 'master' branch, 'testing/master' could be a 'testing' branch, 'next/master' could be a 'next' branch, and 'dev/master' could be a 'dev' branch. Alternately, you could have two repos, the main one and a '-dev' one, and put all of 'next', 'testing' and stable (called 'master') in the main one -- that way everything that the community shares control over is in -dev, and everything that the tech lead controls is in the other one.

You could further simplify by having 'stable' releases just be tags within the 'master' branch of the main repo, so things would look like this:

• two repos, the main one and '-dev'
• the main repo, and dev/master, are writable only by the tech lead
• the main repo has a 'master' branch, and a hotfix branch for each release
• the role of 'testing' vs 'stable' is just tags in the main repo's 'master' branch
• the role of 'next' is filled by the -dev repo's 'master' branch
• throw-away integration testing is done elsewhere (mb a 'seen' branch, or a personal branch by the tech lead within the dev repo)
• the main principal is now: all feature development is in the -dev repo; the main repo does accept patches directly from various people, but is only for feature-frozen bugfixing/stabilization

hmm, i kind of like that simplification. You could go even further, consolidating everything that is tech-lead-only into one repo, and then just having personal repos outside of that:

• same as above except replace dev/master with a 'dev' or 'next' branch within the main repo. The throw-away integration testing could be a branch named 'edge' or 'experiment' or 'trash' or 'try' or something like that (i like 'try'). This has some virtuous simplifications:
• ppl only have to remember that the only branches to base something off of are either /master or /dev
• mb dev should be called 'new' b/c that's easy to remember (and shorter than 'next')

so the next, one-repo-plus-personal-repos system would be:

• master branch: holds releases, hotfix branches and prereleases which are -alpha and above
• new branch: what we were calling 'next'
• try branch: what we were calling dev/master

I bet ppl will just submit their pull requests to 'master' however, and develop from 'master', which isn't what we want (we want new development off 'next'). So how about:

• master branch: what we were calling 'next'
• one branch for each release: holds prerelease testing, the release, and then hotfixes
• try branch: what we were calling dev/master

i like that. Maybe 'try' is a confusing name tho. Mb 'trial' is better. Or 'edge'. So:

One repo. Two branches: 'master' and 'edge'. And then one branch for each release.

Eh, just make the releases in master. So sorta back to git flow. How about:

One repo. Two branches:

• master: the prereleased version alpha and above, plus any hotfixes
• and anonymous hotfix branches for each release; maybe named branches for the hotfix branches for the still-supported releases
• dev:
• this is what we were called 'next'
• no official 'seen'/'edge' branch, so that ppl don't get confused and base off of it (or mb have one called 'experiment/dumpsterfire/trash'?)

all of master/test/dev have linear histories, but dev is rebased off of each new release. master < test, master < dev.

Problems:

• rebasing 'dev' on 'master' all the time will mess everyone up if they base on 'dev'. Isn't there a better way? Maybe just merge dev into master? I think what [5] [6] does is maybe to not actually merge 'next' into 'master', but rather just to merge the things that succeeded in 'next' into 'master'. So everyone would be basing on 'master', not on 'next'

oh, i see, yes that's it:

" Decide what to base your work on.

In general, always base your work on the oldest branch that your change is relevant to.

    A bugfix should be based on maint in general. If the bug is not present in maint, base it on master. For a bug that’s not yet in master, find the topic that introduces the regression, and base your work on the tip of the topic.

    A new feature should be based on master in general. If the new feature depends on a topic that is in seen, but not in master, base your work on the tip of that topic.

    Corrections and enhancements to a topic not yet in master should be based on the tip of that topic. If the topic has not been merged to next, it’s alright to add a note to squash minor corrections into the series.

    In the exceptional case that a new feature depends on several topics not in master, start working on next or seen privately and send out patches for discussion. Before the final merge, you may have to wait until some of the dependent topics graduate to master, and rebase your work.

    Some parts of the system have dedicated maintainers with their own repositories (see the section "Subsystems" below). Changes to these parts should be based on their trees." [7]

So:

version numbers: marketing, break, normal, hotfix

prerelease tags: -0, -alpha, -preview, -beta, -rcN

• 0: use this (appended to the master version that it's based off of) as a placeholder in fields where you need to put a version number but the version is actually not a release. If you are planning to share this with others and reference the 'version', instead start with the base master version and then append a dash followed by (some shortening of) your name and then some indication of which version it is (maybe a date and a sequence number); eg '-bshanks-201212-0'
• alpha: developers should be using this to test it. Feature frozen. Always builds, passes active automated tests. All code has been reviewed and signed-off by code owners/lieutenants.
• preview: closed beta (only invited users should be using this to test it). Otherwise like beta.
• beta: open beta (adventurous users should be using this to test it). Must have been alpha tested. No known blocking bugs.
• rcN: release candidate #N. Must have been beta tested.

repos:

• just one repo

branches:

• unstable: throw-away integration branch. May have history rewritten, accept merge commits. Should always build but otherwise may not work. Other commits should NOT be based on it.
• dev: Linear history but rebased upon each release. Only some or no commits in here may be tagged, but all commits always build, pass active automated tests. All code has been reviewed and signed-off by code owners/lieutenants. Other commits should NOT be based on it (or if they are, will have to be rebased before adding to master) -- an exception is commits that are dependent on other work being done by someone else after the most recent master.
• master: the latest out of: prerelease -alpha thru -rcN, releases, or hotfixes on top of the latest release. Only tech lead may write to this. All commits should be based on this. Linear history.

approval dispositions:

• reviewed-by: a reviewer approved of it
• signed-off: a lieutenant or code owner signed off

roles:

• reviewer: someone with the power to review code
• committer: someone with commit access to the dev repo
• lieutenant or code owner: A committer to whom the tech lead looks to to approve changes in certain topics or files (via signoffs). Lieutenants/code owners may not want to look at code until after it has been reviewed by someone else.
• project lead: in charge of what gets released (in charge of the repo)
• stable maintainer: in charge of bugfix releases, and probably has a veto on what gets released and what gets marked preview, beta, rcN

Workflow:

• unstable is a throw-away integration branch to test out merging various work
• project lead accepts merges into 'dev'
• these merges should be (re)based onto the most recent 'master'
• when the head of the master branch is a release (not a prerelease), and the project lead feels that it's time to push out a new version, they stop accepting new features into 'dev' and if necessary, pare down 'dev' to try to find a subset of 'dev' that is worthy of being an alpha release. Once 'dev' looks like an alpha release, they start to pull everything that went into that 'dev' into 'master' (rebasing and with fast-forward merges?; should they do any required rebasing in 'unstable' and then fast-forward merge 'unstable' into 'master'? or do they do that in 'dev'? or locally?). When it's working, they tag the head version in master with 'x.y.z.0-alpha'. After this they can continue new feature development in 'dev' in parallel with feature-frozen development in 'master'.
• when the stable maintainer believes that a version in the master branch has met the criteria for a preview/beta/rc release, they tag it as such
• when the stable maintainer believes that a release candidate has met the criteria for a release, they tag it with the release version number (without a prerelease tag)
• the project lead then rebases/rebuilds the dev branch based upon the new release at the head of master
• if bugfixes/hotfixes are required to old releases, a bugfix branch is made from that release in master. The fourth version number is incremented. Typically bugfixes should also be applied to dev and experimental.

Analogies to other workflows:

• git flow: master is like git flow's master and release branches, bugfix branches are like git flow's hotfix branches
• Linux kernel workflow: both master and dev are like Linus's tree. experimental is like the linux 'next' tree
• Gitworkflow: dev is like gitworkflow's next, experiment is like gitworkflow's seen, master is like gitworkflow's master, bugfix branches are like maint branches

Alternatives:

• ask ppl to rebase onto the current 'dev'. This means that when cutting a new 'master' the maintainer doesn't have to rebase (if they want a linear commit history), but the tradeoff is that everyone else is doing rebases instead. I kind of like that actually..
• i kind of like this actually
• could also define a 'merge window' when the head of the master branch is a release (not a prerelease), and at that time people rebase and submit pull requests onto an evolving dev or master. This suggests maybe creating a separate 'next' for this function, to allow 'dev' to evolve even outside of the 'merge window'.

---

i spent some time recently checking into the recent arguments for an email-driven git flow instead of something like GitLab?. I am not persuaded.

The most persuasive argument for an email-driven git workflow is that some famous people do it:

• the linux kernel (and note that Linus founded git)
• the git project itself

sr.ht also popularizes an email-driven git flow (i dunno if sr.ht is as famous though).

However i can't find arguments for it that persuade me:

https://kernel-recipes.org/en/2016/talks/patches-carved-into-stone-tablets/ (discussion: https://lwn.net/Articles/702177/ https://www.reddit.com/r/programming/comments/73gpys/why_linux_kernel_development_still_uses_email/ ) says:

• email is quicker (okay but presumably gitlab etc has an api and there is some commandline/emacs/etc integration of gitlab etc that can make it just as fast)
• email is async (agree this is good, but i don't think it's enough for me to choose email)
• email is easier (well maybe it was but i think these days gitlab is just as easy for most ppl; also apparently webmail or MS exchange makes git email flow hard, and a lot of ppl use webmail or MS exchange)
• github has to duplicate email's functionality (okay but now that gitlab exists and is free, that's already been taken care of)
• email clients benefit from other work, eg accessibility etc (true but not enough for me to choose email)
• the speaker even says that he uses Github for a smaller project and that it is better for 'drive-by patches' and maybe for new contributors, but that the email workflow is better at scale
• by linearizing review of all patches onto one email list, all devs see the code review/discussion on all patches (okay but at scale the list has too much traffic and devs don't read the messages relating to patches they are not interested in; and the speaker already said that email is only better at scale)

this link from the LWN discussion disagrees with many of the points from the previous article: https://lwn.net/Articles/702357/

https://ipfs.io/ipfs/QmdA5WkDNALetBn4iFeSepHjdLGJdxPBwZyY47ir1bZGAK/comp/linux/git_basic.html suggests that email is simpler

https://blog.brixit.nl/git-email-flow-versus-github-flow/ (discussion: https://lobste.rs/s/kevlgd/git_email_flow_vs_github_flow ) says:

• no need to deal with rebasing because patches are isolated (sure but now the maintainer has to discover conflicts (or semantic conflicts and test failures) after applying the patch, rather than the submitter discovering these before making a pull request)
• and if you rebase, then github can't detect local merges, and you have to use the merge button in the web browser (apparently not true according to )
• maintainer doesn't have to (half) live in the web browser (okay but presumably you could use a github/gitlab API similarly)

https://drewdevault.com/2018/07/02/Email-driven-git.html (discussion https://news.ycombinator.com/item?id=17441060 ) describes the email git workflow but doesn't give many reasons for it, besides 'email clients benefit from other work' above.

In the discussion though the author makes a good point, which is that sr.ht is merely trying to offer the best of both worlds, so that contributors who want a gitlab-style experience can have it, and contributors who want an email-driven workflow can have that too. He opines that technically, gitlab etc should have been based on and extend email behind the scenes, rather than reinventing email (presumably he means via issues/pull request discussion threads), and he is merely trying to do it that way. I agree with this.

https://begriffs.com/posts/2018-06-05-mailing-list-vs-github.html gives some better reasons for the email-driven flow:

• threading in email is better; github only has single threading (plus the ability to add comments to the diff itself)
• an email discussion can expand to cover multiple people's patches at once; a github pull request discussion is only about one pull request ("patches from multiple authors can’t mix in a Github pull request")
• if the submitter goes away, it's easier for someone else to take over for them in an email discussion
• email allows you to adapt your diff format; github is stuck with the format github chose
• discussion about the abstract proposal is intermixed with discussion about the patch itself, rather than being separated into an issue discussion and a pull request discussion; this is better of iterative back-and-forth improvement of both the abstract proposal and the patch at the same time, which is common
• each person can choose their own mail client

i suspect that the real reason email is used is just that gitlab/github didn't exist back in the day, and now these early projects have a workflow that works for them (with customizations that work for them e.g. the 'patchwork' tool, so no reason to change.

---

on whether or not to have a linear commit history:

• the first part of this article describes 3 options (merge commits, squash and merge, rebase and merge): http://blog.danieljanus.pl/2021/07/01/commit-groups/
• ppl note that what the author is asking for in the second part of the 'commit groups' article is kind of what git already provides when you use merge commits (with --no-ff), b/c the other git commands have various options like git log --first-parent, git bisect --first-parent, git log --merges, git log --topo-order, git log --topo-order --no-merges: https://news.ycombinator.com/item?id=27727527 https://lobste.rs/s/r8wvoj/things_i_wish_git_had_commit_groups#c_kd3jje
• and for git show: git show --first-parent COMMIT # perspective of target branch = branch you were on when merging, git show -m COMMIT # perspective of both branches, Lengthy explanation and more ways to do it: https://stackoverflow.com/questions/40986518/git-show-of-a-merge-commit, git diff COMMIT_BEFORE_MERGE..MERGE_COMMIT