Basic respository organization #1
Conversation
* There are going to be several more developer files of various types, so best to just start making some space for them now.
* github treats the "docs" directory as magic and (should) find README, code of conduct, etc. in there, so this lets us have them render both in Sphinx and on github.
* This is marked as rST but in a way that should be compatible with Markdown. * It's not obvious that github will note this as a "real" CoC but that is something that can be dealt with later.
* Bug report and enhancement.
* Based on SpacePy
* This avoids the 'can this be closed?' question on an issue that takes a lot of work and discussion.
jtniehof
added
the
documentation
* Quick scrub to remove the most egregiously out-of-date information
* Issue template for requesting dev access. * Consistent use of <url> for files that might be parsed as rst or md. * Remove stray reference to SpacePy in enhancement PR template.
* Code style/standards (and pylint) * Documentation style/standards * Pull request workflow
* This makes sure the autosummary is built from the docstrings.
* Copy button from SpacePy, allows hiding of prompts and output in Python examples so can easily copy/paste.
|
I think this is now "done" to the point of bringing us up to basic functioning as a project. To avoid scope creep, I suggest we focus on things that this PR adds or changes that need further changes, or things that are essential to basic project operation that this PR needs added. Existing things in e.g. documentation that need to be fixed should probably be pushed off to other issues or PRs, as well as other fanciness (e.g. would love to have logo and/or nice header for the documentation.) |
|
As Denis and I discussed, I've moved Andrew and Meilin to developers rather than project admins, as they'll likely be contributing code moreso than project organizing. That's the only change since the PR came out of draft. |
|
Also added Xiaoguang as developer. @balarsen , this has removed your approval, so if you could slap approved again it would be appreciated. |
|
Was missing some words in the pull request workflow; fixed (08ca1e9). |
|
You want me to merge it or are you still working on this? |
|
Good to merge...I'm not really working on it, just occasionally finding horrible typos when I look at stuff, but any future findings can be their own PR. |
merge master
This is one omnibus PR that will have all the basic files to set up the repository and organization. This top description will be updated as commits are added (so it might be more up to date than discussion below!) I'm making this as a draft PR so comments can come in as commits are added, and will check things off the TODO list (and add things to them.) If it seems necessary, descriptions of items will also go below.
TODO List
Code of conduct
This is in place. Apparently github does some magic to recognize if it's a "real" CoC but this is based on the SpacePy one, which works, so I'm hopeful. This is marked as .rst but it's also valid Markdown per https://gist.github.com/dupuy/1855764 ...I was just hoping to avoid having to add Markdown rendering to Sphinx, so we'll see how this works in practice.
README
README was updated and moved into docs dir. Eventually most of it should probably move into Sphinx docs but there's some useful stuff. Added comments on current status, relationship to SpacePy, etc.
Issue/PR templates
One PR template, based largely on the SpacePy one.
Two issue templates, one for bugs and one for enhancements, based the SpacePy issue template and targeting to each possibility. Blank issues are still enabled so people can make general queries. I can see having more templates in the future (e.g. docs question, general user help, requesting dev access) but no sense going overboard right off.
License/copyright
I added two separate files: one for the license and one for the copyright. Github tries to auto-detect the license so I'm hoping that putting it in its own file will help with that. Please double-check this is okay....I'm including the copyright claim to their contributions for non-LANL contributors, since this is a derived work from the LANL code. (I will also probably put in the NASA contracts that supported development.)
With this in place, do we need a separate copyright notice on all 200 files?
Contributing
I focused the CONTRIBUTING file on the basic "how do I get code in? How do I become a developer?" because all the standards, etc. will be several separate documents in the Sphinx/rST docs (most of which are mentioned above.) It seemed reasonable to have a minimum contribution for development; very occasional developers can submit PRs.
Similarly there's a list of contributors. Everybody that's contributed code is in the contributor list (including an option for former developers); then there's a dev list (with admins highlighted.) Right now I'm saying there are no "former" developers since that's defined by commit access to the repository, but there's one person in particular who's put in a lot of work that I'd like to have marked as such.
PR workflow
pull_requestsprovides both a little bit of HOWTO and also standards (at this point, suggested standards) for when to merge.Code, documentation standards
code_standardsanddocumentationhave suggested standards for code style (including commit messages) and documentation style. dbprocessing obviously isn't currently compatible with them, but I think it's worth agreeing on standards before trying to enforce them. Please do look them over, as they represent largely my personal preference right now...I'm happy to defend those choices. We can change them later but best to get some agreement now.Sphinx template
I played around with the built-in options and went with the sphinxdoc scheme (which I think is what SpacePy is using.) There are more built-in themes here and a whole mess of others that are grabbable here but it doesn't seem worth an enormous amount of work right up front.