betterscientificsoftware / bssw.io Goto Github PK

GitHub notifications are tricky. This article gives some good pointers.

http://alexking.org/blog/2011/11/28/not-getting-github-notifications

The topic of tools for software documentation came up during discussion in the CSE17 minisymposium on How to Succeed with Open Source Software, organized by Brian Adams and Damon McDougall. Damon kindly volunteered to spearhead curating content on this topic. Thanks, Damon!

Let's try doing this as an 'aggregate' resource to facilitate input of content by multiple people on subtopics, if needed.

https://hbr.org/2014/12/your-agile-project-needs-a-budget-not-an-estimate

placeholder for Judy to curate

DOE doesn't have sustainability initiatives focused on long-term software products (that I know of). AFAIK larger projects are mostly programmatic and depend mainly on sometimes short-term research funding.

Make a how-to on growing software projects within the DOE. Ideas:

• discretionary funding sources at the labs
  • often this is reserved for maintenance/sustaining existing capabilities, NOT research
• LDRD, ASCR, other traditionally research-focused funding sources
• SBIR
• subcontracts, and companies that can help (Kitware, Krell, others)
  • can be cheaper than hiring within the labs
• communication channels for advertising software within DOE
  • who to talk to, where to present so that people find out about software
  • potential focus area for facility liaisons -- spreading the word.
• software release and licensing at the labs
  • who to talk to, what to be aware of when releasing software at the labs
  • potential link for how to choose a license.
• How to lower barriers for external DOE contributors.

I'd like to work with others on this as I don't have the internal perspective on labs other than LLNL.

Create curated content file, following style of HowToEnablePerformancePortabilityForCseApps.md

Need 1- and 2-line descriptions for the topics within the Collaboration category.

Mini-WhatIs will also be required, but are not covered in this issue.

Note that #51 covers the licensing topic specifically as a pilot.

Author: Greg jarrah42

Add resource for CSE17 minisymposium.

Need 1- and 2-line descriptions of the topics in the Planning category.

Mini-WhatIs are also needed for all topics, but are not covered in this issue.

Write 1- and 2-line descriptions for all topics in the Cross-Cutting category.

Mini-WhatIs are also needed, but are not covered by this issue.

The operational intensity introduced in the Roofline model -- operations per byte of DRAM traffic -- is a simple model that can be used to determine what architectures are the best match for a given computational kernel, or conversely, in what ways to optimize a kernel so it performs better on a given architecture. Operational intensity is not typically provided directly by performance tools but can be estimated from other readily available measurements.

Curated article with overview of several tutorials on testing.

• Overview text
• Item 1

Etc.

This page, or aggregate page, would contain curated links to journals and similar mechanisms for making your software citable as academic literature and getting citation-based credit for scientific software development. A preliminary list of options follows, whose descriptions may need improvement by people who are more familiar with each journal:

• TOMS (ACM Transactions on Mathematical Software): This is a well-established journal whose articles often describe novel algorithms and their implementation as mature, usable software products. It has also pioneered policies to improve the reproducibility of published research.
• TOMACS (ACM Transactions on Modeling and Computer Simulation): Another well-established journal, which deals more with applications, their impact and results, as well as their methodology (e.g. Verification & Validation).
• JSS (Journal of Statistical Software): Like TOMS, but with a focus on software which implements statistical methods rather than other mathematical modeling topics.
• SoftwareX: An Elsevier journal which aims to ensure software is cited and gets credit in the literature. This journal accepts submissions regarding software that is used in any of a wide range of disciplines, from mathematics to the sciences and humanities.
• JOSS (The Journal of Open Source Software): This journal provides authors with a DOI for their software package without requiring a full-length manuscript. Instead, authors must demonstrate (via a form of peer review) that their package follows certain best practices of open-source software, including proper licensing and documentation, and helps meet scientific research challenges.
• Zenodo: Like JOSS, Zenodo can provide a DOI for your software. Unlike JOSS, it does not require a review of the software, and can generate a DOI for each release of your package via GitHub integration. Zenodo also allows users to upload data, and obtain a DOI for their data, while also acting as a hosting/distribution platform for others to access that data.

Describe the process for creating an article for BSS. Include a decision tree to help the writer decide on the best type of article and how to best create it.

Create a file in the format of a blog post, containing all metadata expected to be used for a blog post

Add initial content

Author : @oamarques
EB member: Rinku
There a quite a few groups working on reproducibility in science, with a focus on scientific software. However, there doesn't seem to be much coordination between them, nor any obvious place to go for a guide on how to get started or what are best practices. This page could provide a starting point for scientists/developers interested in trying to improve this aspect of their work. It could provide links to the broader community, as well as a survey of the current best practices and links to get people started.

Write two brief articles on the BSS definitions of Productivity and Sustainability.

Create curated content file, following style of HowToEnablePerformancePortabilityForCseApps.md

http://www.economist.com/news/science-and-technology/21695377-professors-unprofessional-programs-have-created-new-profession-more

Better Testing: Start Today

Concerned about testing, but so hard to cover existing code, not enough resources.
Instead, resolve to cover new functionality with tests.
From now on:

• No source contributions without tests.
• A source checkin without tests coverage is a fault. Can and should be reported by anyone.

I would like to add a How-To on simple ergonomics adjustments and health related exercises to fend off negative health effects of sitting for hours in front of a computer screen day after day, year after year as part of a career in software development.

There are a whole lot of other organizations already working on ways to sustain open source projects, scientific and otherwise. BSS should link and leverage these efforts.

This would add a page to the site pointing to a number of recent key work on software sustainability, including:

• GitHub's Open Source Guides: opensource.guide

• reports, e.g. Nadia Eghbal's Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure

• foundations/non-profits devoted to OSS, e.g.:

  • NumFOCUS: sustaining open source projects for data science
    • (Spack is now a NumFOCUS affiliated project, along with many others you've probably heard of from Python/R ecosystems
  • Linux Foundation
  • Ford Foundation
  • Sloan Foundation

• recent NSF software sustainability efforts

• Information on similar efforts in DOE (This site? Others if they exist?)

  • this could grow into a separate howto on how to grow OSS projects at national labs. (funding sources, who to talk to, etc.)

• others?

Author: Rinku (@rinkug)

The following link has a nice summary of free online courses in computer programming:

https://medium.freecodecamp.com/370-free-online-programming-computer-science-courses-you-can-start-this-month-fc5b9867769e#.ff8i6qd83

[Rinku] Updated article (aug 2020) on the same topic can be found at https://www.freecodecamp.org/news/free-online-programming-cs-courses/

This article has relevant advice for people who step into technical leadership roles on a software project. Some points could be very relevant for our community.

https://www.infoq.com/news/2015/01/technical-leadership-agile

Why do programmers wear headphones? For the same reason that you can’t juggle.
https://hackernoon.com/why-do-programmers-where-headphones-5ca3a2f81266#.ykhfxv2b4

Write a 2-line description and a mini-WhatIs on licensing for the Collaboration: Licensing topic

Author: @rinkug
EB member: @bartlettroscoe

Provide resources on how to establish and follow coding conventions (or standards) in order to create maintainable code. This will be a series of how to's, curated links and other articles.

Create curated content file, following style of WhatIsPerformancePortabilityForCseApps.md

Add instructions for creating an GitHub issue prior to writing an article for BSS.

https://medium.com/the-mission/extraordinary-results-are-disproportionately-created-by-fewer-actions-d0488a62aee3#.1alebqx03

Need 1- and 2-line descriptions for the topics within the Individual Productivity category.

Mini-WhatIs as also needed, but are not covered in this issue.

Create a file in the format of a sample announcement, containing the metadata an announcement should have.

After creating the file

https://github.com/betterscientificsoftware/betterscientificsoftware.github.io/blob/master/CuratedContent/CseCollaborationThroughSoftware:Improving%20ProductivityAndSustainability.md

the BSSW site will not build.

curated pointer to a journal article: Aziz Nanthaamornphong, Jeffrey C. Carver (2015), Software Quality Journal, p. 1-30, Springer US, url, doi:10.1007/s11219-015-9292-4

Curation of performance portability related content

This is the first project where I have really used the GitHub Projects feature for implementing a Kanban process (but I did play with it a little on other project and was not impressed). While I understand the benefits of using a native GitHub tool for implementing Kanban, I have to say it leaves a lot to be desired. I will not compare GitHub Projects to JIRA (because there is no comparison, JIRA blows GitHub Issues and GitHub Projects out of the water in every way for project planning and issue tracking but JIRA is a commercial tool). Instead, I will compare this to waffle.io which is another free tool that implements Kanban using GitHub issues and is used for Trilinos and TriBITS which I have used a lot.

First the advantages of using the GitHub Projects feature over waffle.io:

• With GitHub Projects, you can associate a single GitHub Issue or PR with more than one Kanban board and it can be in different stages in those board. (But this may not actually be an advantage because I don't see any utility for this when compared to what you can do with filters on labels with waffle.io.)

Second, the really irritating aspects of GitHub Projects:

• You have to switch to the Project page and then manually add a new "Card" (which is an Issue or PR, of course) to add an Issue or PR one of the Project stages. This is a slow workflow.
• The drop-down to add a new card does not let you just put in the Issue or PR number (i.e. #1234). Instead, it makes you search based on a name and drag the cards over. This is a slow workflow.

Now for the main advantages of waffle.io over GitHub Projects that I am noticing the most:

• Using waffle.io one can assign and change the Kanban stage right in the GitHub issue using a label. One only needs to view the Kanban board when one wants to with waffle.io
• One can define various filters for a waffle.io Kanban board based on labels, assignee, milestones, issues and/or PRs. With GitHub Projects, you can't filter on anything. (The ability for create filters makes it unnecessary to support multiple Kanban boards like GitHub Projects supports.)
• Because labels are used to represent Kanban stages with waffle.io, you can create quick GitHub queries for "ready" or "in progress" issues, for example, or any other type of query supported by GitHub for Issues. (Ironically, you can't search for GitHub issues by their GitHub Project or the stage in that GitHub Project.)

So while the GitHub Projects feature for implementing a Kanban process and Kanban board may get better over time, currently is is pretty bad and I don't see why anyone would use it while waffle.io is available.

So why is BSS using GitHub project instead of waffle.io?

Anyone want to debate this?

CC: @maherou, @curfman, @jwillenbring

Improve customer confidence in your updates

When a customer updates to a new version of your software, changes are not just about new features, but often (perhaps mostly) include improvements to existing capabilities.

When a customer is integrating your latest version, they are looking for changes in behavior. Changes include timing differences and changes in input requirements and output data. In HPC software, changes in output can be common, especially with floating point computations, where difference in order of operations can produce correct but different results.

In these situations, customers don’t necessarily mind that results have changed, but they want to know that the change is expected, not the result of a regression.

Improve customer confidence in your update by considering the following:

• Create an issue in your database (e.g., a GitHub or JIRA issue) for the feature and give it a label indicating that the feature may change software behavior from the user’s perspective.
• Notify known users of the change prior to release.
• Document any changes that result in different behavior from your software.
• Describe in release notes what kind of behavior change can be expected.
• Provide users with an option to restore previous behavior (e.g., via a runtime or compile time parameter).
• Include performance differences, even if the changes are improvements.

Some sources for behavior change:

• Performance optimizations for vectorization: Vectorization represents one of the current commodity performance improvement curves. The number of simultaneous operations a process can perform (as either SIMD or SIMT), we continue to increase as a resource for concurrency. Introducing vector operations into your code, directly or through compiler transformations, will result in floating point results differences, including differences from one architecture to the next.
• Reordering of irregular (gather/scatter) computations for better performance: Changes in the order of irregular computations can improve cache utilization and reduce memory bandwidth requirements, leading to better performance. These changes also lead to floating point result differences.
• Changes in heuristics for automatic parameter settings: Many algorithms are tunable, able to exploit problem details to improve robustness, reliability or performance. Automatic parameter setting can improve software usability by reducing how many details the user needs to explicitly manage. Improved heuristics, often derived from customer use, can lead to changes in behavior, even though the change is an improvement.

Need 1- and 2-line descriptions of the topics in the Reliability category.

Mini-WhatIs are also needed for all topics, but are not included in this issue.

Create curated content file, following style of HowToEnablePerformancePortabilityForCseApps.md

Web platforms such as InfoQ, medium.com often have very useful articles that could be of interest. We could consider an article focused on which sites are of interest to our community.

Plan and schedule training classes or workshops and develop documentation needed to help IDEAS-ECP team and code teams/facilities facilitate productivity on the three ASCR computing platforms. an example is advertising the adoption of the Spack package management tool.

We've been using docker/containers for quite a while now, and it is very good at encapsulating complex packages with their dependencies, for use on any Linux/x86 system. Also can be used for continuous integration/automated testing, and will be important for HPC too.

I could write an article, if it would be useful.

Need 1- and 2-line descriptions of the topics in the Performance category.

Mini-WhatIs are also needed for all topics, but are not covered in this issue.