From owner-freebsd-hackers@freebsd.org Mon Jun 24 17:45:30 2019 Return-Path: Delivered-To: freebsd-hackers@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 5D69215D3D1A for ; Mon, 24 Jun 2019 17:45:30 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-qt1-x832.google.com (mail-qt1-x832.google.com [IPv6:2607:f8b0:4864:20::832]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id D919877EAF for ; Mon, 24 Jun 2019 17:45:28 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mail-qt1-x832.google.com with SMTP id w40so4848574qtk.0 for ; Mon, 24 Jun 2019 10:45:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdimp-com.20150623.gappssmtp.com; s=20150623; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=/CueTMrZsSuAkEmaN1L8sJk2REVGN2bBs+aGTIeZeHY=; b=atYNuDhf9oR8ZBOREzcAVlgETP7vt+8yxHH+4pHVVQEdogPjOWAtw6KUnvY/EkSnJc 5gcsSPVZ259t8o1zyRp6+nSzjLo0DpsQeITpNC1lIMQQRpJQBJ+dWM90+qZ5C3S1aj5p 5jqq2spMMabO0BzLKblOCKiJT5VLAj4b1wCPrv/WvgWi2QP7PRblRyvsRuhJ9qrTyOcc svvfcOvskM6k3qMGagYt17HkZnLDOsI4oOAKtIJHMWA2r0r7sm+cpc6XetKM9MgARZ/1 6DzQ4KtXw+SdzRBQS+B5orll5jP+uvus1uGsxqYZsEtNWptm6qqGXmB3ic3c0a0VT3sY /opA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=/CueTMrZsSuAkEmaN1L8sJk2REVGN2bBs+aGTIeZeHY=; b=BZVU14jaP1em0AVS2vYM+JppzwxRstRe4Mp7hge8XPldMow9cSFg+b4TfKEARmc8Po oX1LNnaVVCqU+l12w2b9TqTOG5PXzy9JREmyvg2swir9X/4/uv0TB+JOTiVdy68AMZ6C xuX4vLcZO5HEHuFWU/wcowRHGU3O4E3yfhQCljEWllBPkfWYSwuLqTyw4hOWghOnBMaE MwvbnqAGsrALI88LIaPSctR431SrKE2SMkVS4+y/owUwpT0RGQ42HBGGeFMTFuAUURVo W5UOll6gMi2qx9gtyWiOMYdL74anKS2H9BrCHPaE4zHycBzkl/g8EMlV28b3jd5GYpHh hsRQ== X-Gm-Message-State: APjAAAUt0n0yPdRHI/M5ES9OomCfFTsNb8EKuQw88iX6TrNKB2saXym7 6luaTId/e1hgYXkKEP2CYmqI0Y6NwNV+MkucZvBNrQ== X-Google-Smtp-Source: APXvYqw9nt8ssM74ESl/9TKQxabWjV5ReCOzyP48K0vMaHJ1rjKbSKyhgw7bj8Qw6uW5ioXrXPBgRwfN2T9GS1fTmvA= X-Received: by 2002:aed:3e1d:: with SMTP id l29mr117565524qtf.175.1561398327968; Mon, 24 Jun 2019 10:45:27 -0700 (PDT) MIME-Version: 1.0 References: <201906241629.x5OGTmpd044504@gndrsh.dnsmgr.net> <2BD397BB-FD96-4A06-9263-DD35B2CA494D@cschubert.com> In-Reply-To: <2BD397BB-FD96-4A06-9263-DD35B2CA494D@cschubert.com> From: Warner Losh Date: Mon, 24 Jun 2019 11:45:16 -0600 Message-ID: Subject: Re: release notes file To: Cy Schubert Cc: "Rodney W. Grimes" , "freebsd-hackers@freebsd.org" , "Bjoern A. Zeeb" , Mark Johnston , FreeBSD Release Engineering Team X-Rspamd-Queue-Id: D919877EAF X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=bsdimp-com.20150623.gappssmtp.com header.s=20150623 header.b=atYNuDhf X-Spamd-Result: default: False [-4.90 / 15.00]; ARC_NA(0.00)[]; TO_DN_EQ_ADDR_SOME(0.00)[]; R_DKIM_ALLOW(-0.20)[bsdimp-com.20150623.gappssmtp.com:s=20150623]; NEURAL_HAM_MEDIUM(-1.00)[-1.000,0]; FROM_HAS_DN(0.00)[]; TO_DN_SOME(0.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; MIME_GOOD(-0.10)[multipart/alternative,text/plain]; PREVIOUSLY_DELIVERED(0.00)[freebsd-hackers@freebsd.org]; DMARC_NA(0.00)[bsdimp.com]; URI_COUNT_ODD(1.00)[5]; RCPT_COUNT_FIVE(0.00)[6]; TO_MATCH_ENVRCPT_SOME(0.00)[]; DKIM_TRACE(0.00)[bsdimp-com.20150623.gappssmtp.com:+]; MX_GOOD(-0.01)[cached: ALT1.aspmx.l.google.com]; RCVD_IN_DNSWL_NONE(0.00)[2.3.8.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.4.6.8.4.0.b.8.f.7.0.6.2.list.dnswl.org : 127.0.5.0]; NEURAL_HAM_SHORT(-0.90)[-0.902,0]; R_SPF_NA(0.00)[]; FORGED_SENDER(0.30)[imp@bsdimp.com,wlosh@bsdimp.com]; MIME_TRACE(0.00)[0:+,1:+]; RCVD_TLS_LAST(0.00)[]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; FROM_NEQ_ENVFROM(0.00)[imp@bsdimp.com,wlosh@bsdimp.com]; IP_SCORE(-2.99)[ip: (-9.43), ipnet: 2607:f8b0::/32(-3.15), asn: 15169(-2.33), country: US(-0.06)]; RCVD_COUNT_TWO(0.00)[2] Content-Type: text/plain; charset="UTF-8" X-Content-Filtered-By: Mailman/MimeDel 2.1.29 X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 24 Jun 2019 17:45:30 -0000 On Mon, Jun 24, 2019 at 11:06 AM Cy Schubert wrote: > On June 24, 2019 9:29:48 AM PDT, "Rodney W. Grimes" < > freebsd-rwg@gndrsh.dnsmgr.net> wrote: > >> On Mon, Jun 24, 2019 at 9:44 AM Cy Schubert > > > >> wrote: > >> > >> > On June 23, 2019 5:36:16 PM PDT, Mark Johnston > >wrote: > >> > >On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote: > >> > >> On 23 Jun 2019, at 19:18, Mark Johnston wrote: > >> > >> > >> > >> Hi, > >> > >> > >> > >> > Today we add a Relnotes tag to commits that warrant a release > >note. > >> > >> > My impression is that it doesn't work so well: if a committer > >> > >forgets > >> > >> > or doesn't know to add one there's no way to amend the commit > >> > >message > >> > >> > (same for MFCs), and a commit message isn't a convenient place > >to > >> > >> > write > >> > >> > the text of a release note. I would like to propose adding a > >> > >> > top-level > >> > >> > RELNOTES file instead, which like UPDATING would document > >notes for > >> > >> > specific commits. It would be truncated every time the head > >branch > >> > >is > >> > >> > forked, and changes to it would be MFCed. This fixes the > >> > >> > above-mentioned problems and would hopefully reduce the amount > >of > >> > >time > >> > >> > needed by re@ to compile release notes. > >> > >> > >> > >> Hooray. Can we put that file into the doc repo, so that the > >ports > >> > >> people, and the docs people, and all other kinds of hats can put > >> > >things > >> > >> in there as well? > >> > > > >> > >Virtually all of the 12.0 release notes are for src/ (there are 4 > >lines > >> > >for ports/pkg and 1 line for docs, and the latter describes a new > >man > >> > >page in src). Why is it important to have a single place for > >everyone > >> > >to commit their entries? > >> > > > >> > >> Oh, the release notes go into the doc repo anyway. Can we just > >put > >> > >them > >> > >> in the right place and just fill them from a skeleton where they > >> > >should > >> > >> be and naturally grow the document (feel free to use a different > >> > >markup > >> > >> language once doc is ready for that). > >> > >> > >> > >> Oh, with that release notes are written automatically and you > >are > >> > >still > >> > >> responsible for that your stuff is in there. And the release > >notes > >> > >only > >> > >> need an editing pass in the end? > >> > >> > >> > >> And the wiki pages like ?What?s cooking for 13?? or similar > >could > >> > >> just vanish as we?d have these updated at least every 10 minutes > >> > >> automatically .. on our web server under /releases/ where they > >belong > >> > >.. > >> > >> > >> > >> How amazing would that be? > >> > > > >> > >I would guess that many src committers simply won't add release > >notes > >> > >if > >> > >they have to commit to a second repository and use some unfamiliar > >> > >markup format and worry about validating the file. There are lots > >of > >> > >__FreeBSD_version bumps that go undocumented until someone else > >goes in > >> > >and fills in the missing entries. A plain-text file in src repo > >for > >> > >src > >> > >release notes is low-friction and creates only marginally more > >work for > >> > >RE. "What's cooking for 13?" can just point to the copy of > >RELNOTES in > >> > >svnweb. > >> > > > >> > >That said, I personally would try to commit my release notes to a > >doc > >> > >repo file if one existed. I've spent a few minutes trying to > >compile > >> > >the 12.0 notes on my desktop and have not been able to get past, > >> > >"cannot > >> > >parse > >http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl". > >> > >So, I'm probably not a good person to set up release notes for > >13.0. I > >> > >will help fill in entries for commits since the 12.0 if someone > >else > >> > >does that setup. > >> > >_______________________________________________ > >> > >freebsd-hackers@freebsd.org mailing list > >> > >https://lists.freebsd.org/mailman/listinfo/freebsd-hackers > >> > >To unsubscribe, send any mail to > >> > >"freebsd-hackers-unsubscribe@freebsd.org" > >> > > >> > Src and ports should each have their own RELNOTES file. > >> > > >> > The only operational concern I have is trimming the file, probably > >when a > >> > branch goes EOL. > >> > > >> > >> I'd add truncating the file on -current to the list of things we do > >when we > >> branch. then we can MFC RELNOTES as we MFC the features they > >describe. > > > >I disagree, truncating the file on -current destroys the list of > >changes that are still in current that need to get into the next > >set of release notes. > > > >Howerver there is 1 point on head/ to truncate the file. > >That is when we create a new .0 branch as that is the tree state > >that has nothing to put in the release notes. This may be the > >most sane path forward that I had not thought of before. All > >other branched versions can just continue to grow until EOL. > >This bounds the file to about a 2.5 year collection in head/, > >and a 5.0 year collection in stable/. > >It may make since to truncate on stable/X when stable/X.Y's > >are created. > > > >I think we need to be fairly careful with the MFCing of this, > >that may work fine for things that are commited with a RELNOTES > >entry, something in the back of my head is screaming lots of > >merge conflicts but I can not put a solid finger on it. > > > >Something just hit me, what commit number goes in this file, > >if we list it by rXXXXXX of head, that has a rYYYYYY when MFC'ed, > >probably need to track both? Which means all existing entries get > >an added line at stable/X creation to indicated the commit that > >created the branch? If we try to simplify and only track by > >head commit that makes it harded to go find the MFC and see > >if there was merge munging to make it work. > > > >> Warner > > Which is why trimming at branch EOL probably makes the most sense. It's > simple and easy to implement. > I don't understand this at all. When we branch a new stable release, we know that on the new current release we have nothing not in the release notes file. What does branch EOL have to do with that? > As for what to do about MFCs and more specifically conflicts, conflicts > will be unavoidable. IMO conflicts with RELNOTES will be as likely as with > UPDATING or Obsoletefiles. > Yea. If we keep the structure of the file super simple (like markdown), then it doesn't matter. You fix the conflicts and go. The merged version need not be tracked since you know it's merged if it is in RELNOTES, and most MFCs don't replicate the full context of the original commit any, but just have a pointer to it. Warner