[Infrastructure] Baseline Requirements - Markdown Output

Tue Nov 27 10:30:10 MST 2018

Makes sense.

Thanks,

Ben

From: Ryan Sleevi <sleevi at google.com> 
Sent: Tuesday, November 27, 2018 10:28 AM
To: Ben Wilson <ben.wilson at digicert.com>
Cc: infrastructure at cabforum.org
Subject: Re: [Infrastructure] Baseline Requirements - Markdown Output

Thanks Ben. I see you merged it in to master already.

If you were doing that to preview changes, there's an easier way to do that, before committing. If you look at that URL with the PDF, you'll see the word "master", which refers to the "master" branch. When you made your edits, you created a new branch called "Footnote-and-Indenting-Change" ( https://github.com/cabforum/documents/tree/Footnote-and-Indenting-Change ) and a new Pull Request ( https://github.com/cabforum/documents/pull/118 ).

When you created the Branch, you'll see that Travis CI kicked off (it's the little green arrow next to the commit on that second page). Because it completed, a preview of your change was available at https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/Footnote-and-Indenting-Change/BR.pdf

Note how the word "master" has changed to the name of your branch ("Footnote-and-Indenting-Change") in that third URL.

This is how you can preview any of the changes you're making on a branch, as you're making them. This will hopefully allow easier feedback and making more comprehensive changes.

One other note, since I saw something quirky about your change - when merging, you probably want to do "Squash and Merge" instead of "Merge". https://help.github.com/articles/merging-a-pull-request/ shows how to select "Squash and Merge" in the interface, with more technical details at https://help.github.com/articles/about-pull-request-merges/ if you care how Git/GitHub work. The TL;DR: is that "Squash and Merge" lets you change a bunch of tiny commits into one 'logical' commit. This is particularly useful when you're trying to accomplish one 'logical' thing, but may require several cycles of edit-commit-preview to make sure it's looking like you'd like. You can make a bunch of those tiny changes, and then just do "Squash and Merge" at the end to make them a single commit (i.e. "Fix indenting").

Hope this all helps!

On Tue, Nov 27, 2018 at 12:09 PM Ben Wilson <ben.wilson at digicert.com <mailto:ben.wilson at digicert.com> > wrote:

For what it’s worth, I edited the Github version to place the footnote for “public suffix” adjacent to the paragraph in which it appears and I changed “code boxes” to regular indenting so that the lines don’t cut off on the right side. 

See  https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/master/BR.pdf

From: Infrastructure <infrastructure-bounces at cabforum.org <mailto:infrastructure-bounces at cabforum.org> > On Behalf Of Ben Wilson
Sent: Monday, November 5, 2018 10:02 AM
To: Ryan Sleevi <sleevi at google.com <mailto:sleevi at google.com> >
Cc: infrastructure at cabforum.org <mailto:infrastructure at cabforum.org> 
Subject: Re: [Infrastructure] Baseline Requirements - Markdown Output

Thanks,  Ryan.

I think we ought to change what we can (presentation issues) and re-generate the PDF.  

Also, I like the way that the automated generation method (not the one I used) adds page numbers and doesn’t insert a page break before the section headings for the tables.

From: Ryan Sleevi <sleevi at google.com <mailto:sleevi at google.com> > 
Sent: Monday, November 5, 2018 9:27 AM
To: Ben Wilson <ben.wilson at digicert.com <mailto:ben.wilson at digicert.com> >
Cc: infrastructure at cabforum.org <mailto:infrastructure at cabforum.org> 
Subject: Re: [Infrastructure] Baseline Requirements - Markdown Output

And here are the versions automatically being produced as part of our infrastructure:

https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/master/BR.html

https://cabforum-travis-artifacts.s3-us-west-2.amazonaws.com/builds/master/BR.pdf

I would presume that, in context, we have a couple requirements from the past discussions about format:

1) A format that folks can edit without the use of/requirement of certain platforms and/or third-party software

2) A format that is stable between versions (i.e. opening in a newer version of some software won't change the formatting)

3) A format that produces stable output (e.g. two different people can produce the same output and ensure there aren't visual differences/artifacts)

It's unclear, from the context of requirements, whether there is a fourth requirement

4) Assuming all those things above are equal, a format that minimizes the number of steps to produce output should be preferred over other formats, on the basis that more steps to produce output creates more opportunities for human error or requires more manual intervention

Separately, both versions of the documents (what Ben provided and what's being produced) 'suffer' from the same formatting issues at present. One is the use of footnotes re: "registry-controlled" (which appear at the end of the document, rather than the page printed on) and the other is the use of block formatting in the profile.

With respect to the ballots themselves, the footnote is controlled by Ballot 96 ( https://cabforum.org/2013/02/20/ballot-96-wildcard-certificates-and-new-gtlds/ ) and doesn't require any 'special' treatment - i.e. without requiring a new ballot, the presentation of that section 'could' be adjusted. With respect to the block formatting (see 5.4.1, 7.1.2.2, 7.1.2.3), that's fairly easy to fix and presentational, without changing any of the text.

I'm specifically avoiding the suggestions of making structural or balloted changes to those documents in this WG, given the charter.

On Mon, Nov 5, 2018 at 10:00 AM Ben Wilson <ben.wilson at digicert.com <mailto:ben.wilson at digicert.com> > wrote:

FWIW - Here is what it looks like when I export BR.md to PDF using Typora.

_______________________________________________
Infrastructure mailing list
Infrastructure at cabforum.org <mailto:Infrastructure at cabforum.org> 
http://cabforum.org/mailman/listinfo/infrastructure

_______________________________________________
Infrastructure mailing list
Infrastructure at cabforum.org <mailto:Infrastructure at cabforum.org> 
http://cabforum.org/mailman/listinfo/infrastructure

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20181127/311220a1/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4934 bytes
Desc: not available
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20181127/311220a1/attachment-0001.p7s>