Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Spec cleanups #441

Merged
merged 9 commits into from
Apr 12, 2021
Merged

Spec cleanups #441

merged 9 commits into from
Apr 12, 2021

Conversation

DanielOaks
Copy link
Member

This PR does steps 2+3+4 in #329 - cleans up the specs, puts them in a more defined folder structure, and unifies the titles (both how they're named, and also removing useless duplicated Markdown titles).

I've left Metadata and SASL alone for now, since there's some non-trivial PRs to those.

@DanielOaks
Unify spec titles, remove version numbers.
73a02b2 
We've changed fns for all but Metadata and SASL because those specs have
pending PRs/updates and I don't want to stomp over them with these.
@DanielOaks
Fix duplicate markdown headers.
cf427e0 
Also make WebIRC's title consistent with stuff like multi-prefix again.
@DanielOaks
Reorganise specs under new folder structure.
df72efd 
Again, we're not moving Metadata yet because open PR, but it'll go under
the `/extensions` folder for sure.
@DanielOaks
Review changes.
35fe8dc 
- Kill the "IRCv3" from start of titles.
- Keep killing core.
progval
progval reviewed Feb 27, 2021
View reviewed changes
Copy link
Contributor

@progval progval left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix duplicate markdown headers.

Shouldn't you add a new header at the beginning, eg. ## Description for consistency with https://ircv3.net/specs/extensions/echo-message-3.2.html ?

Reorganise specs under new folder structure.

Shouldn't they all have a redirect?

@DanielOaks
Copy link
Member Author

DanielOaks commented Feb 27, 2021 •
edited
Loading

re markdown headers I was thinking that yeah, ## Description or ## Introduction or whatever - will need to see what fits for each spec. Will throw another commit on top adding them, thanks for the yell.

Yeah I've added redirects from their old locations to their new ones, redirect_from key in the yaml header auto-creates redirect files.

@DanielOaks
Unify spec initial-page-titles.
0aa1a8b 
Mentioned in example-spec.md, but essentially: "Introduction" is for the
first section of a multi-section spec, "Description" is for the main
body section when a spec only contains one section, and "Motivation" is
used when the spec author wants to split out the introduction/descript
from the motivation of the spec I guess.

Makes all our spec appear much more nicely on the website, I assure ya'.
@DanielOaks
Copy link
Member Author

Cool, I'm fairly happy with this now. Some of these changes are made for the sake of consistency across our specs, but I've tried to only touch the initial header terms / metadata / file structure and no actual spec text here. Good step forward, not the last, keep an eye on #329 for future work I plan to do on our existing specs, and throw additional suggestions in there. Reviews + merge pls.

@jwheare
Copy link
Member

jwheare commented Feb 28, 2021

Looking snazzy. Can you make a draft pr to the website repo that refs this branch for the submod so we can preview it?

@DanielOaks DanielOaks mentioned this pull request Feb 28, 2021
Closed
@DanielOaks
Copy link
Member Author

DanielOaks commented Feb 28, 2021 •
edited
Loading

Draft website view: https://deploy-preview-355--ircv3.netlify.app/irc/ (I haven't bothered changing where the links on that page point, but the redirects will change you to the right new path anyway).

@DanielOaks
/best-practices -> /docs.
8bedd4d 
More general, I can see different sorts of documents fitting in there
while "best-practices" is relatively limited.
@DanielOaks
Take SNI out of /specs/.
4efe3ce 
I think it'd fit better under ircv3.net/docs/* and the way to do this
right now is just putting it in the website repo directly, instead.
We'll see what people think about this change.
@DanielOaks
Copy link
Member Author

So I'd like SNI, and future stuff like the clients loading urls considerations document to live outside of https://ircv3.net/specs/ since they... don't really fit there, I reckon. More appropriate under a different root folder on the site, say https://ircv3.net/docs/* instead. So I've taken that document out of this repo, and I'll throw it into the website repo when these changes get merged. Down the line, once we have more than like, one or two documents, we could have a generic repo for docs vs specifications, but that's work that can be really easily done in future given the very few documents along these lines that we have right now.

@jwheare
Copy link
Member

jwheare commented Mar 23, 2021

Is this good to go?

@DanielOaks DanielOaks merged commit df2f2f2 into ircv3:master Apr 12, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@progval progval progval left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@DanielOaks @jwheare @progval