Document how we deprecate things #2192
Conversation
sauclovian-g
requested review from
RyanGlScott,
ChrisEPhifer and
mccleeary-galois
|
The failures are #2166 again, not anything I did. sigh |
There was a problem hiding this comment.
Thank you for adding these (desperately needed) sections to the manual, @sauclovian-g! Besides a couple of minor numbering typos (and the implied need to rebuild the PDF), this appears ready to merge.
@sauclovian-g This is very much my fault. I gave the go-ahead to implement the saw.galois.com redirects at the DNS level once the "Introduction to Verification with SAW" was moved, when instead we should probably simply replace the old site's contents with a "We moved!" message + timed redirect to the new page. Speaking of the new tools.galois.com page, I'm going to think about and open a ticket for the new manual synchronization problem we're going to have with that. Hopefully, I will be able to use my edit access there to simply trigger an edit request whenever |
|
Well, #2166 should get fixed for real, the problem is that stupid things are happening... |
Also add some glaringly missing text about REPL actions (e.g. :q) and then about enable_experimental and enable_deprecated as context. Part of #2184.
sauclovian-g
force-pushed
the
2184-deprecation-docs
branch
from
7a31cc8 to
59bedc6
Compare
| * `:type` or `:t` checks and prints the type of an arbitrary SAWScript | ||
| expression: | ||
| ~~~~ | ||
| sawscript> :t show | ||
| {a.0} a.0 -> String | ||
| ~~~~ |
There was a problem hiding this comment.
The inline code below needs to be indented to match the bullet point here, or else it will be formatted strangely:
* `:type` or `:t` checks and prints the type of an arbitrary SAWScript
expression:
~~~~
sawscript> :t show
{a.0} a.0 -> String
~~~~
There was a problem hiding this comment.
It came out ok when I looked at it (both with GH's rendering and in the PDF) ... although in the PDF having it come out indented one more notch would look better. Unfortunately, indenting it causes the tilde-line to not be recognized and makes a mess, at least in pandoc. So... I guess not 😿
There was a problem hiding this comment.
Interesting... does pandoc understand the triple backticks (```) instead of tildes? I know that GitHub respects indenting code blocks that use triple backticks, if nothing else.
There was a problem hiding this comment.
That does seem to work, and it does look a bit better that way. At this point it should probably wait until Chris is done hacking and slashing, but I've put it in my queue so it won't get completely forgotten.
| * `:help` or `:h` prints the help text for a built-in function or | ||
| command: | ||
| ~~~~ | ||
| sawscript> :h show | ||
| Description | ||
| ----------- | ||
|
|
||
| show : {a} a -> String | ||
|
|
||
| Convert the value of the given expression to a string. | ||
| ~~~~ |
There was a problem hiding this comment.
(same with this one)
| 3. The objects in question are removed entirely and are no longer | ||
| available. | ||
|
|
||
| In general any object or group of objects will move only one step per | ||
| release; that is, something first marked deprecated (so it warns) in | ||
| saw-script 1.2 will not disappear by default before saw-script 1.3 and | ||
| not be removed entirely before saw-script 1.4. | ||
| The time frame may be longer depending on the needs of downstream | ||
| users, the complexity of migration, and the cost/impact of keeping the | ||
| deprecated code in the system. | ||
|
|
||
| We may move faster if circumstances dictate, but hope not to need to. | ||
|
|
||
| Objects that have never appeared in a release, or that have never | ||
| moved past experimental may be removed without first being deprecated. | ||
| However, we aim to avoid this in cases where the objects in question | ||
| have gotten substantial use despite their formal status. |
There was a problem hiding this comment.
Those last paragraphs aren't supposed to be part of entry 3 so I think it's ok. (Indenting the body of each list entry doesn't seem to be necessary as long as there's no paragraph break.)
Sorry in return; we kind of rushed it in last night so it wouldn't be in the way of Chris hacking on the manual today. |
No description provided.