René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Decide how to format Misc/NEWS entries","articleBody":"Now that we have chosen what NEWS tools to go with, I'm starting a fresh discussion on how exactly we want to format the entries.\r\n\r\n-----\r\n\r\n@larryhastings [said](https://github.com/python/core-workflow/issues/6#issuecomment-290591614):\r\n\r\nI haven't found the time to sit down and write this properly, so here's a quick note on this topic before Brett makes up his mind.  sorry if it's a bit long / messy.\r\n\r\nFirst, I don't have a strong opinion about what the input format to blurb should look like.  If there was a consensus about \"it should look like X\", then I'd make it look like X.\r\n\r\nWe don't seem to have a consensus about what the input format should look like, because I don't think we've reached consensus about what metadata the tool needs.  We need to figure that out first.\r\n\r\nObviously necessary:\r\n1. the Misc/NEWS text\r\n2. the Misc/NEWS category\r\n\r\nI would also like:\r\n3. some datestamp/nonce that ensures the news entries remain in some sort of stable order (I prefer chronological ordering, sadly git doesn't maintain timestamps)\r\n\r\nI believe Brett is also asking for:\r\n4. an optional \"please consider for the next What's New document\" flag\r\n5. a suggested category for \"What's New\"\r\n\r\nBy the way, towncrier's approach of pre-created directories named for the categories (2.) is a nice idea.  That ensures people don't misspell the category name.  blurb could easily switch to that.  the only downside I know of is that iiuc git doesn't track directories as first-class objects, so we'd have to have an extra empty file in each directory.\r\n\r\n\r\nblurb current supports 1-3.  it uses the filename for two bits of metadata (stable sorting order and category), and the contents of the file are simply the news entry.  but it's kind of reached my comfort level regarding storing metadata in the filename.\r\n\r\nif we only want to add 4, a simple \"consider for what's new please\", then okay I think we could live with sticking that in the filename.  Like we add .wn just before the extension, for example.\r\n\r\nif we want to add 5, then my inclination is to add a *simple* metadata blob to the contents of the file:\r\n* simple name=value (or name: value) pairs\r\n* `#` is a line comment\r\n* empty line or some explicit marker line (\"--\") ends the metadata blob\r\n\r\nIf we do that, then my inclination is further to move all the metadata into that blob:\r\n* `category=Library`\r\n* `nonce=20170513062235.ef4c88a1`\r\n* `# what's new = Improved Modules`\r\n\r\n(uncomment \"what's new\" to use it)\r\n\r\nThe \"blurb\" tool would make it easy to add these, but users could also create the file by hand using a web page form that formats the output for them.  (Making the entry entirely by hand might be tricky, since the nonce should be in a standardized format.  Maybe we could give them a short blob of Python they run to generate one?)\r\n\r\nIf all the metadata lives inside the file, then we don't care what the filename is, it just needs to be unique.\r\n\r\n-----\r\n\r\n@ncoghlan [said](https://github.com/python/core-workflow/issues/6#issuecomment-290604103):\r\n\r\nFor metadata-in-the-file, I quite like the format that the Nikola static blog generator uses:\r\n\r\n```\r\n.. title: The Python Packaging Ecosystem\r\n.. slug: python-packaging-ecosystem\r\n.. date: 2016-09-17 03:46:31 UTC\r\n.. tags: python\r\n.. category: python\r\n.. link: \r\n.. description: Overview of the Python Packaging Ecosystem\r\n.. type: text\r\n\r\nPost starts here...\r\n```\r\n\r\nAs an added bonus, when the file has the `.rst` extension, my editor automatically grays out the metadata as line comments, and assuming we're planning to use ReST in the snippets for ease of Sphinx integration, that would also apply here.\r\n\r\nUsing structured metadata like that would also open up future options for acknowledgements that aren't directly tracked in the git metadata - cases where we built on a patch written by someone else, or someone contributed API design ideas that someone else implemented, etc. At the moment we put that in the snippet body (\"Initial patch by ...\" and so forth), but a metadata field could more easily feed into ideas like auto-generating Misc/ACKS in addition to Misc/NEWS.\r\n\r\nAs far as a stable sort algorithm for display goes, we could then define that as:\r\n\r\n- a date field in the snippet metadata (e.g. the date string Nikola uses is just `datetime.utcnow().strftime(\"%Y-%m-%d %H:%M:%S UTC\")`)\r\n- the filename used for the snippet (since that has to be non-conflicting or git will complain)\r\n\r\n","author":{"url":"https://github.com/brettcannon","@type":"Person","name":"brettcannon"},"datePublished":"2017-03-31T16:33:34.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":50},"url":"https://github.com/66/core-workflow/issues/66"}