Skip to content

Guide to Post Categories (Types) and Tags (Topics)

C.A.M. Gerlach edited this page May 25, 2018 · 2 revisions

The basic idea is that since categories are mutually exclusive (only one can be applied per post), we use them to denote the type/purpose of the post, which should generally fit only one; while tags, since they are intended to be more specific and applied in multiple, should denote post topics and subtopics, of which there can be several.

Categories

  • Releases are for release announcements for Spyder and directly affliated projects/plugins (i.e. those under the spyder-ide organization; this can include formal public betas, release candidates, and final releases)
  • Previews are for first looks at features, enhancements, and new plugins/projects before first release (alphas can be included here).
  • Status is for core project and development-related updates internal to the project, like project status/direction/schedule changes, summaries/reviews of project progress, regularly scheduled updates, development milestones, incremental updates of future milestones, tentative plans, appeals for dev/testing/funding help, etc, Development milestones internal to the project itself should be categorized here (feature-complete, Github stats, etc). Would be more properly termed an "Update" to fit with the theme of the others, but didn't want it to be confused with a Release
  • News is for any developments involving something external to the project, like funding awards/sponsors, major personnel additions (new developer on the team, dev taking on major new role, or departure of key dev team member), Spyder getting featured in another publication or significant blog, an upcoming or past conference attendance/presentation, and items relating to third-party Spyder-related plugins, integrations, collaborations, etc. Milestones external to the core project, like OC donations or social media engagement, should be categorized here.
  • Tutorials is for content who's primary stated purpose is Spyder-related help, guides, how-to, tips, etc.
  • Other is for anything that doesn't fit into the above categories. The above should pretty much cover anything, but one naturally cannot expect the unexpected.

Tags

Tags are generally straightforward and can be added to if appropriate and agreed upon (i.e. the tag would be expected to receive at least a few relevant posts per year). Main areas for addition are mentioned below. Tag groups below may be intended to be exclusive (i.e. only one of the group should be used) or non-exclusive (as many as applicable should be used); generally, the purpose of exclusivity is to either ensure posts don't acquire too many tags as to make them less useful, or to help tightly focus the content of posts so as to keep readers engaged and target more, shorter posts rather than a few long dissertations

  • Spyder3, Spyder4 Usage: For anything, particularly Releases, related to those respective branches Additions: On new major release/branch) Exclusivity: Nominally non-exclusive (i.e. for items that directly apply to both branches, or specifically discuss both), but both should be applied with care to items that don't directly relate to the core Spyder program)

  • new-release, major-release, minor-release, point-release, beta Usage: To indicate the appropriate type of release (generally following the semantic versioning convention) for any Release announcement of Spyder, affiliated projects (qtpy, docs, etc) or plugins; new-release should be reserved for 1. The first public release of a package/plugin, and 2. The first final/official 1.0/stable release of the same. beta can also be used for released candidates or alphas if desired, if separate tags aren't warranted for them Additions: Possibly release-candidate and/or alpha if warranted, otherwise none expected Exclusivity: Exclusive, except possibly new-release with alpha or beta

  • development should be used for any Preview,, Status, or other post related to Spyder development information, plans or progress

  • feature, enhancement, change Usage: Generally for Preview posts showcasing one of these three elements (will necessarily apply to most or all such posts), but could potentially be applied to Announcements or other posts as well that specifically focus on a feature (new integral functionality), enhancement (improvement to an existing functionality), or other change (a notable modification to Spyder that doesn't fall under the above, like a deprecation/removal, moving the docs, packaging change, techdebt, API change, etc). Additions: Probably none Exclusivity: Exclusive

  • plugin, spyder-unittest, other plugins as needed etc Usage: To indicate that the post content (any type) relates to a Spyder plugin, and possibly the name of the plugin Additions: Yes--the name of any plugin when first posted about, if its a plugin officially under the spyder-ide organization and that's likely to receive multiple blog posts Exclusivity: Both plugin and (if applicable) {plugin-name} should be used, possible multiple if directly relevant

  • guide, others (tips, etc?) Usage: For Tutorials, to indicate the type of help/informational material posted. In this case, a guide leads the users through a series of steps to accomplish a specific objective. Other possibilities could include tips, one or a collection of hints and tricks regarding the application (useful editing shortcuts, handy IPython magics, etc), maybe introduction (introduces the purpose and basic usage of a new feature/function with less formality than documentation), or explanation (for a more in-depth dive into a specific Spyder-related behavior or concept, like @ccordoba12 's Stack Overflow post on static vs. dynamic introspection and how that played out in Spyder) faq listing common questions and answers about a specific plugin, feature, module, etc., etc. Additions: Yes, when a genuinely distinct type of help/tutorial material is posted, like the above examples Exclusivity: Generally exclusive, but not always if a post contains substantial amounts of multiple types of content (focus should be kept tight unless clearly demanded by the content)

  • status-update, roadmap, appeal, (internal) milestone Usage: Generally for a Status post, to indicate the type of internal status-related information being presented. Additions: Possible, if a genuinely distinct, non-one-off type of status-related post was needed Exclusivity: Generally exclusive except for status-update and any one of the others, but not always if a post contains substantial amounts of multiple types of content (focus should be kept tight unless clearly demanded by the content)

  • (external) milestone, team, media, presentation, award Usage: Generally for a News post, to indicate the type of news bite being presented. Additions: Possible, if a distinct type of notable news item occurred with at least moderate frequency Exclusivity: Generally exclusive, if a post is sufficiently tightly focused

Clone this wiki locally