Fix up/update CONTRIBUTING #2201
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add doc/internal/developer.md as a general spill area for things we
might put in CONTRIBUTING but that a new developer doesn't actually
need to see right away.
Also move the issue label documentation to its own file as it turns
out it's rather large (about a quarter of the total line count in
these files...)
This adds a bunch of stuff from our processes and practices
discussions last summer, but not really everything yet; there'll want
to be another go, and possibly another reorganization first. We
should see how we feel about the way this is laid out in another
couple months.
Some things to specifically note:
- I updated the repository layout summary; it was quite out of date;
- Mention a bunch more tools you want if you're developing;
- Mention what4-solvers;
- Mention that on MacOS you need a real JDK and not the placeholder
the system ships with;
- Say not to do git submodule --init --recursive;
- Link to a bunch of the open issues related to these topics.
sauclovian-g
added
type: enhancement
sauclovian-g
requested review from
RyanGlScott,
ChrisEPhifer and
mccleeary-galois
Comment on lines
+228
to
+232
| # Documentation | ||
|
|
||
| So far there is nothing that needs to be said here that isn't in | ||
| [../../CONTRIBUTING.md](CONTRIBUTING). | ||
|
|
There was a problem hiding this comment.
N.b. If we merge this before #2202 (likely), I'll update this section with a link to the doc/README.
Comment on lines
+35
to
+37
| Currently to build the manual you need `pandoc`. | ||
| This is expected to change as we migrate the manual to Sphinx. | ||
| See issue [#2197](https://github.com/GaloisInc/saw-script/issues/2197). |
There was a problem hiding this comment.
Another comment mostly for my own benefit, so I remember to adjust this as we merge this and #2202.
Comment on lines
+246
to
+414
| much easier for someone who is a writer, but doesn't really understand | ||
| what you're doing, to tidy up such text than to write the whole thing | ||
| from scratch. | ||
| If you would like help with writing, say so when you file a pull | ||
| request or ask out-of-band. | ||
|
|
||
| ## Documentation Tools | ||
|
|
||
| The miscellaneous documentation files scattered around the tree | ||
| (e.g. all the various READMEs) are written in Markdown. | ||
| Markdown is more of a concept than a standard; the condition of | ||
| satisfaction for changes is that these files render acceptably | ||
| in GitHub's Markdown viewer. | ||
| Note that when reviewing a pull request you can open a file in that | ||
| viewer via the "..." menu in the top right corner of each file's | ||
| diffs; choose "View File" there. | ||
|
|
||
| The larger documents are currently written either in Markdown and | ||
| built with `pandoc`, or written in ReStructured Text and built with | ||
| Sphinx. | ||
| Updates should render correctly in the built version. | ||
| Ideally updates should also render correctly on GitHub, but this may | ||
| not always be feasible. | ||
| The various documentation builds are orchestrated with (GNU) make. | ||
|
|
||
| The source format for all of these tools is plain text. | ||
| This allows managing the documentation source files with git. | ||
|
|
||
| ## Writing Documentation | ||
|
|
||
| There are several practices that we attempt to follow with | ||
| documentation sources. | ||
| These are intended to help restrict diffs to the text actually | ||
| changed, which make diffs smaller and easier to read, which in turn | ||
| makes changes easier to review (and easier to merge) and considerably | ||
| reduces development friction. | ||
|
|
||
| 1. Don't generate long lines. | ||
| Have your text editor word-wrap at somewhere between 60 and 70 columns. | ||
|
|
||
| 2. New sentence, new line. | ||
| When starting a new sentence, begin it on a new line. | ||
| Don't reflow whole paragraphs; reflow only single sentences. | ||
|
|
||
| 3. Avoid making changes to lines you aren't actually making substantive | ||
| edits to. | ||
| Sometimes this means introducing an extra line break or two where | ||
| you otherwise might reflow. | ||
|
|
||
| 4. Commit whitespace and formatting (source formatting/layout) changes | ||
| separately from content changes. | ||
| (Thus, if you end up with too many extra line breaks or the like, | ||
| such that things get ugly or unreadable, fix it up as a separate | ||
| commit.) | ||
| Document such changes in their commit messages to help reviewers | ||
| skip over them. | ||
|
|
||
| ## Using Mergify | ||
| 5. Embedded links can be long and not play nicely with word-wrap; if | ||
| one gets ugly, put it on its own line. | ||
|
|
||
| If you find that your editor is violating these principles for you | ||
| (e.g. refusing to let you have reasonable-length lines, or reflowing | ||
| text without being asked) and you can't figure out how to stop it, ask | ||
| for help. | ||
|
|
||
| A couple tips for writing effective Markdown: | ||
|
|
||
| - You need a blank line before the first entry of a list, and between | ||
| entries. | ||
| If you leave the initial blank line off, strange things happen. | ||
|
|
||
| - The whole of each list item should be indented past the bullet point. | ||
| This normally doesn't matter if you have a single paragraph, but if | ||
| you want multiple paragraphs or have other markup it can be important. | ||
|
|
||
| ## Updating Prebuilt Copies | ||
|
|
||
| For some of the large documents (currently without much intentionality | ||
| or pattern) a prebuilt PDF file is included in the repository. | ||
| This is for the use of people browsing in their local checked-out | ||
| clones of the tree, or on GitHub, who may not want to (or be able to, | ||
| respectively) build the documentation themselves. | ||
| These copies should be updated whenever any of their sources change, | ||
| using the following procedure: | ||
|
|
||
| 1. Commit all the sources. | ||
|
|
||
| 2. When necessary (for changes that affect text that propagates via | ||
| the SAW executable, such as the doc strings for the SAW intrinsics), | ||
| rebuild SAW itself. | ||
|
|
||
| 3. Rebuild the PDF. | ||
|
|
||
| 4. Commit the updated PDF with a commit message along the lines of | ||
| "Regenerate the prebuilt manual". | ||
|
|
||
| This makes sure that all the ingredients are fully up to date and that | ||
| any and all metadata built into the PDF reflects the commit that | ||
| changed the text. |
There was a problem hiding this comment.
Thanks very much for writing up this detailed section about documentation! I will be sure this gets appropriately updated (like earlier comments, likely as part of / after #2202).
ChrisEPhifer
approved these changes
Jan 28, 2025
|
I think we should land yours first, partly because this is vague on some of the stuff in there (because it hadn't appeared yet when I wrote it), plus there are a couple things they should align on (e.g. the eventual name of doc/internal) ... and there's not really any rush. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.