Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Blog: Technical properties of sustainable software #2139

Merged
merged 27 commits into from
Sep 27, 2024
Merged

Blog: Technical properties of sustainable software #2139

merged 27 commits into from
Sep 27, 2024

Conversation

bartlettroscoe
Copy link
Member

@bartlettroscoe bartlettroscoe commented Aug 20, 2024 •
edited
Loading

Description

EB Member: @ksbeattie

Resolves https://github.com/betterscientificsoftware/bssw-blog-planning/issues/35

Blog article "Technical Properties of Sustainable Software".

PR checklist for files displayed on bssw.io site

  • [Author] @mention the BSSw.io editorial board member @<eb-member-id> in Description above assigned to shepherd your PR.
  • [Author] Add the <issue-id> in the Description above for the associated GitHub Issue.
  • [Author] Ensure wikize_refs.py -i <base>.md is run and commit (if using wikize_refs.py) ... Can't run again due to issue with wikize-refs.py
  • [Author] Inspect the content in the *.md file(s) as rendered in GitHub for this PR.
  • [EB Mem] Assign this PR to the EB member <eb-member-id>.
  • [EB Mem] Assign this PR to the author of the PR <pr-author-id>.
  • [EB Mem] Add one or more Reviewers.
  • [EB Mem] Add label content: <content-type> for the type of contribution.
  • [EB Mem] Add to Project Content Development (see Content Development).
  • [EB Mem] Add meta-data to the *.md file(s) (set Publish: yes).
  • [EB Mem] Add label preview (so PR branch will be merged to 'preview' branch and watch for possible merge failures).
  • [EB Mem] Rebuild preview site and confirm new content is there, renders correctly and is returned in searches.
  • [Author] Make any final changes to the PR based on feedback.
  • [ ] [Author] Ensure wikize_refs.py -i <base>.md is run and commit (if using wikize_refs.py). ... Can't run again, see above
  • [EB Mem] Rebuild preview site and re-confirm content looks correct.
  • [EB Mem] Ensure at least one reviewer signs off on the final changes.
  • [EB Mem] Move the PR to "Ready to Publish" in Content Development.
  • [EB Mem] Leave comment and @mention @betterscientificsoftware/bssw-maint (BSSw Maint) asking to carry out final publication steps.
  • [BSSw Maint] Verify that all needed files are present in the PR (article, images, updates to Site/Homepage.md carousel and/or Site/Announcements/Announcements.md as appropriate).
  • [BSSw Maint] Merge PR. (Should automatically move to "Done" in Content Development.)
  • [BSSw Maint] Verify new contribution shows up on bssw.io as expected.

NOTE:

  • Checklist items prefixed with [Author] are expected to be performed by the author of the PR or can be performed by the author.
  • Checklist items prefixed with [EB Mem] must be performed by a BSSw.io Editorial Board (EB) Member.
  • Checklist items prefixed with [BSSw Maint] must be performed by someone in the @betterscientificsoftware/bssw-maint team (hint: type @, b, s, s, w, -, m to auto-complete to @betterscientificsoftware/bssw-maint).

@bartlettroscoe
WIP: Initial copy of text and starting to fill in
dc5e99f 
This is for betterscientificsoftware/bssw-blog-planning#35.
@bartlettroscoe
WIP: Finished basic formatting of copied text
ef9e86e 
I also added a little more text.
@bartlettroscoe
Finished first fairly complete draft
3e1c928 
I still need to fill in some references and then I can do some more detailed
editing.

According to emails "count-words", this is currently 1935 words long.  (The
target is about 1500 so this could use some editing to reduce length.)
@bartlettroscoe
Add hero image for tech properties of sustainable software blog article
8a8d528 
NOTE: I generated this hero image with Google Gemini Advancec using the
prompt:

  generate an cartoon image of software depicted as a set of gears and showing
  the hand of a mechanic with a wrench

This was the third of three generated images.

If there is a desire for different hero image, it should not be too hard to
generate one.
@bartlettroscoe
Link to hero image
8931966
@bartlettroscoe
Add references, missing meta-ata, todos
a02593a
@bartlettroscoe
Add a missing reference
fa6193b
@bartlettroscoe
WIP: Move references to bottom
c66dfbc 
The tool wikize-refs.py is refusing the recognise the usage of the reference
[se2s-book-2016].  Perhaps this will help?
@bartlettroscoe
Fix reference link for [se2s-book-2016]
47e2792 
The error was confusing but I misspelled one usage
@bartlettroscoe
Run wikize_refs.py on references
ca707b4 
This messed up the numbering and the links.  But I can fix those manually in
the next commit.  I will not run this script on the file after this.
@bartlettroscoe
Manually fix off-by-one reference numbering error caused by wikize-re…
0ab4728 
…fs.py

No sure what happened here but it was easy enough to fix manually.

The tool wikize-refs.py needs more unit testing and test cases.
@bartlettroscoe
Full edit using Grammarly
a6ae730 
NOTE: I also added some missing reference placeholders [???] in case I want to
add those.
@bartlettroscoe bartlettroscoe added the content: blog For blog content label Aug 20, 2024
@bartlettroscoe
Remove some bullet formatting
4f2efa2 
These were left over from when I was using bullets for these paragraphs.
@bartlettroscoe bartlettroscoe added the preview Merge PR to the 'preview' branch to allow display on preview.bssw.io label Aug 20, 2024
@bartlettroscoe
Copy link
Member Author

I merged this to 'preview' and rebuilt the preview site. The article shows up at:

The formatting looks okay and the hero image looks okay.

It think it could use another reading with some more edits but I would like to see what others think about this first.

(But in the meantime, I can add a couple more references.)

@bartlettroscoe
Some more edits after light reading
8f7c4f6 
This reduced the length a little but up to the end of the Summary section this
is still 1931 words (according to emacs 'count-words').
@bartlettroscoe
Add missing references
3c52a6d 
All of the references should be complete now
@bartlettroscoe
Add bullet on code review
d121ef2
@bartlettroscoe
Copy link
Member Author

Hello @betterscientificsoftware/bssw-editorial-board, would one of you be willing to review this blog post? The generated file for preview.bssw.io can be seen at:

@bartlettroscoe bartlettroscoe added this to the 2024-08 Digest milestone Aug 22, 2024
ksbeattie
ksbeattie approved these changes Aug 23, 2024
View reviewed changes
Copy link
Contributor

@ksbeattie ksbeattie left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've made a few minor suggestions, but feel this looks very good.

@bartlettroscoe
Copy link
Member Author

@ksbeattie, thanks for the review! I will respond to your individual comments and make some changes based on your feedback. I will do that after I post the PR for the CC article for #2110.

@bartlettroscoe bartlettroscoe self-assigned this Aug 23, 2024
@bartlettroscoe
Add bullets for usage of more tools, update references
d21f5b6 
I added mentions of code formatters and other tools like static analyzers and
runtime memory checkers, as suggested by @ksbeattie.

I also changed the reference from the book chapter "Testing of Scientific
Software: Impacts on Research Credibility, Development Productivity,
Maturation, and Sustainability" to shorter articles on the bssw.io site
itself.  (We should likely reference that book chapter in those other bssw.io
articles.)

I also added another reference related to testing and had to shift all of the
latter references.  (I could not use wikize-refs.py to do this because of the
off-by-one issue.)
@bartlettroscoe
Update info on software licenses
e7d2750 
Added some more text as suggested in review by @ksbeattie.

I also added a reference for more info on picking an open-source software
license.
@bartlettroscoe
Update text about core domain model documentation
ed72a82 
Improving this text was suggested by @ksbeattie in his review.
@bartlettroscoe
Copy link
Member Author

@ksbeattie, I added some commits to address your review comments.

@rinkug, hopefully this is ready to publish? (it just needs to have the publication date update in the *.md file).

@bartlettroscoe
Copy link
Member Author

@betterscientificsoftware/bssw-maint, this should be ready to publish. (See above checklist.)

NOTE: I addressed @ksbeattie's comments but technically he signed off on the PR as it was, so, unless I made some mistakes with the new commits, this should be ready to publish.

@bernhold
Copy link
Member

Thanks @bartlettroscoe and @ksbeattie for bringing this to closure! We got an article in about the ACM REP conferences that I want to push out first. That was held in June, so it will seem more timely the sooner we can get it out. I'll probably put this one out in the early September slot.

@bartlettroscoe
Copy link
Member Author

I'll probably put this one out in the early September slot.

@bernhold, sounds good to me. (And that will give me a chance to read it again in a few weeks and improve it more before it gets published 😊)

@bartlettroscoe
Slated for September 2024 publication
ddbed24 
Just need to fill in the day on Sept this gets published
@bartlettroscoe
More edits
9285e5d 
I noticed a few things after letting this sit for several days, including a
few typos that Grammarly.com missed.
@bernhold
Copy link
Member

Hi @bartlettroscoe a couple of questions for you:

  1. What is the source of the image you've included as a hero? I want to make sure we have rights to use and we cover any credits that might be required. (That said, I'm not sure we'll end up using it regardless -- we also need to see how it looks as a hero.)

  2. Your link to Code Complete in the references is incorrect -- it actually links to Clean Code

  3. Is this GH repo with PDFs of books legitimate? I don't see any info on the repo or the at the org level that indicates how they were obtained or asserts their legitimacy.

@bernhold bernhold self-assigned this Sep 26, 2024
@bartlettroscoe
Copy link
Member Author

bartlettroscoe commented Sep 26, 2024 •
edited
Loading

  1. What is the source of the image you've included as a hero? I want to make sure we have rights to use and we cover any credits that might be required. (That said, I'm not sure we'll end up using it regardless -- we also need to see how it looks as a hero.)

It was generated using Google Gemini Advanced. (See the commit message 8a8d528).

I don't think this usage violates Google's policy for the usage generated images stated here. (What good would these generated images be if you can't use them for anything?)

  1. Your link to Code Complete in the references is incorrect -- it actually links to Clean Code

Must of been a copy-and-paste error. I will fix that.

  1. Is this GH repo with PDFs of books legitimate? I don't see any info on the repo or the at the org level that indicates how they were obtained or asserts their legitimacy.

I can find a better reference.

@bernhold
Copy link
Member

Consider linking to the publisher's page for the books?

In the past, I've looked at ISBNSearch.org (e.g., https://isbnsearch.org/isbn/9780735619678) though today, it didn't seem entirely reliable.

@rinkug
Copy link
Member

rinkug commented Sep 27, 2024

This is being merged right now since it has to be published in order to highlight it in digest

@rinkug rinkug merged commit ca254b2 into betterscientificsoftware:main Sep 27, 2024
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ksbeattie ksbeattie ksbeattie approved these changes

@bernhold bernhold Awaiting requested review from bernhold

Assignees

@bernhold bernhold

@bartlettroscoe bartlettroscoe

Labels
content: blog For blog content preview Merge PR to the 'preview' branch to allow display on preview.bssw.io
Projects
Content Development
Status: Done
Milestone
2024-09 Digest
Development

Successfully merging this pull request may close these issues.
5 participants
@bartlettroscoe @bernhold @rinkug @ksbeattie @curfman