Maintaining a package - Githubissues

stefaniebutland commented 5 years ago

Who is the audience?

Who might want to know this? What other groups or organizations might be interested?

people who maintain a package
considering taking over maintenance of a package
curious about the topic

Why is this important?

In the interest of software sustainability, ideally each package would have more than one maintainer, but this is relatively rare. rOpenSci wants to help people get comfortable with this role

What should be covered?

best practices to get contributions from other people to your package
top 10 tips for maintaining a package
for a "big" package depended on by many, here is plan to keep the software from going stale; when we decide to remove a function this is what we do
taking over maintenance of a package developed by someone else

Suggested speakers or contributors

maintainer of a "big" package
people who have taken over maintenance of a package:
- chromer now maintained by Paula Andrea
- qualtRics now maintained by Julia Silge
- RSelenium now maintained by Ju Kim
- rsnps now maintained by Julia Gustavsen and Sina Rüeger
- rdpla now maintained by Alyssa Columbus
- webchem now maintained by Erik Sapper

Resources you would recommend to the audience

Taking over maintenance of a software package, by Scott Chamberlain, Maëlle Salmon & Noam Ross, includes maintainer comments and links to other relevant posts by Julia Silge on taking on qualtRics, and to the Package Evolution section of our Software Development Guide

stefaniebutland commented 4 years ago

Comments I've received on topics that should be covered:

what does “maintenance” include (as opposed to development)?
how can people get involved (in a non-intimidating way) and what mentorship avenues are available to support them (especially if this is their first time maintaining an R package).
how much should you invest when you want to repair things that break, while also making the framework a little leaner
- especially relevant for someone who has volunteered to take over maintaining a package developed by someone else
- how much is it ok to change the original package? Julia Silge wrote about her approach to this in Relaunching the qualtRics package
how to tackle issues
who to contact when in trouble
for those not familiar with the whole packaging workflow, where to find resources on: CRAN submission, github workflows (master branch, dev branch), how to tackle issues

LennertSchepers commented 4 years ago

Even if you have quite some R experience, taking over a well-documented package can be a bit overwhelming (e.g. https://github.com/ropensci/mregions). The rOpenSci devguide and Hadley's R package book looks like a vast amount of good documentation, but if you've scheduled 30 min to get started, it's hard to decide where to start. So yes, I would love a community call on this topic. I've read the The contributing guide and the Taking over maintenance of a software package.

These are the first questions/ideas that popped up into my mind that would be most useful in my case (experience with R, limited package experience):

What is the overall structure of a package that follows all guidelines? A very short intro/description on all the directories/files in the package repository will be very handy.
What are folders/files/sections that you have to edit manually, and which are generated automatically (e.g. documentation sections in a script vs automatically generated documentation files,...)
If I want to start with fixing one issue, what are essential parts that I should know before fixing? Should I learn package documentation and testing/continuous integration and all other aspects of R packages,... or are there parts that are necessary and others that are less urgent?
Are there things that should be absolutely avoided? (things that can break the whole package 😱)?
If there are recommended packages when you can choose between several? Got an answer to this question for some here

After a discussion with @damianooldoni and @peterdesmet this afternoon we had a specific question on rOpenSci packages:

rOpenSci builds and hosts a documentation website (https://docs.ropensci.org/), are these updated automatically? Are there things that should be done differently when developing rOpenSci packages? Or parts that are taken over by rOpenSci and that the package maintainer/author shouldn't do themselves?

juliasilge commented 4 years ago

I would also love a community call on this topic, as maintenance in the long term does require some different approaches or priorities than originally developing a package. Like @LennertSchepers, I found some real challenges in taking over even a well-documented package!

It has been almost exactly a year since I took over the maintenance of qualtRics, but it turns out that in my new job that I start next month, I won't use real-world Qualtrics data or have a Qualtrics account. This means, I believe, that it is time for me to pass the maintainership on of this particular package. 😩 I am guessing this also means I may not be a good choice for a speaker for such a community call, at least not as a main source of knowledge, but I would love to be a source of support in some way. If you think it could be an interesting perspective for the summary (for the blog) as someone who took on maintenance and now needs to pass it on again, I would be interested in doing that.

elinw commented 4 years ago

What do you mean by a "big" package?

stefaniebutland commented 4 years ago

What do you mean by a "big" package?

I think that came from a comment originally from Karthik: "for a "big" package depended on by many, here is plan to keep the software from going stale; when we decide to remove a function this is what we do"

skimr would qualify :-)

stefaniebutland commented 4 years ago

@juliasilge your offer of helping a new maintainer out, supporting the transition and noting your near-term priorities are A+.

If you think it could be an interesting perspective for the summary (for the blog) as someone who took on maintenance and now needs to pass it on again, I would be interested in doing that.

Absolutely. I wonder if there's a more permanent place for that kind of knowledge e.g. an addition to our dev guide chapter on Changing package maintainers, if you're already offering to put some thought and effort into that.

Might you be willing to share your specific insights in a ~5-10min talk during the call?

juliasilge commented 4 years ago

@stefaniebutland Yes, I would be happy to share some specific insights about transitioning on/off the maintainer role with about 5-10 minutes of content on the community call. As the plan firms up, we can firm up the scope of what I should cover relative to what other folks want to chat about.

And I will tentatively plan to do the summary for the blog, unless plans change and it makes sense for someone else to do this. 👍

sckott commented 4 years ago

@LennertSchepers regarding your question about docs.ropensci.org: those docs are updated automatically, on each commit to the master branch of the repository. only repositories that show up here https://ropensci.org/packages/ are included (mregions is included). pretty much everything else the maintainer has to do on their own.

Are there things that should be done differently when developing rOpenSci packages?

We like maintainers to follow guidance in our developer guide https://devguide.ropensci.org/ - this may or may not be different from what you'd normally do.

stefaniebutland commented 4 years ago

Interesting development. At rOpenSci staff meeting we talked about doing this call as a (very well-)moderated panel discussion 🤔. Tricky to do in webinar format but a great way to expose diversity of approaches, tips, opinions. Thinking about this

steffilazerte commented 4 years ago

The thought of having other people work on my packages always makes me cringe, not because I wouldn't like the help or contributions, but because I worry that I haven't set things up nicely for others work with. So my question would be: Is there a way that developers can set up their packages to make this transition easier? Even just for contributions, if not a complete transition of maintainers.

wlandau commented 4 years ago

Along those lines, how important or necessary is it to create a formal software design specification to explicitly lay out the architecture and internals? Apparently, this topic gets attention in traditional software engineering circles, but I have not heard much direct discussion in the R community. A bunch of things are unclear to me:

In which situations should I write a formal technical spec?
What should it cover, and in what level of detail?
How do I get started for an already massive and complicated package? (Analogous to @jennybc's discussion question for the testing comm call.)
Where can I find more examples of formal specs in the R community? The following seem to qualify, but I am not sure because they blend in with ordinary user-level documentation.
- http://richfitz.github.io/storr/articles/storr.html
- https://mschubert.github.io/clustermq/articles/technicaldocs.html
Is there a standard location for the technical spec of a package? Is it just like any old vignette, or should it have a standard name, path, and boilerplate structure?

jennybc commented 4 years ago

how important or necessary is it to create a formal software design specification to explicitly lay out the architecture and internals?

I've thought about this some, having taken over maintenance of packages like readxl and usethis. It can take a while to reverse engineer some of the key internal "rules" of a package, just by reading the code. Often you end up violating these unwritten rules, suffering greatly, then gradually figuring what your mistake was and undoing the damage.

Motivated by that experience, in usethis, I started to write down some of my own internal "rules" about how we do things and why:

https://github.com/r-lib/usethis/blob/master/principles.md

That's quite informal (and I've got even more informal documents tucked away in other packages).

But I think for certain types of packages, this sort of document -- and possibly something more formal -- can pay off.

elinw commented 4 years ago

@stefaniebutland If the timing works for me I'd be happy to talk/answer questions about the skimr maintaining experience and the questions you mention. The only caveat is the crazy number of meetings I have at work and so my time is not always my own.

stefaniebutland commented 4 years ago

Thank you @elinw! I'll include you when I do the initial whenisgood survey to choose a date.

maelle commented 4 years ago

Random find (I haven't listened to this) "Learning a New Codebase with Patricia Aas"

Edit: it is a really good podcast/talk with aspects relevant to R too. It was originally a talk https://patricia.no/2018/06/04/reading_other_peoples_code.html

stefaniebutland commented 4 years ago

Mark your calendar!!

Community Call - Maintaining an R Package Wednesday, March 18, 9-10am PT (Find your local time)

Moderator:

Julia Silge

Panelists:

More info about why these panelists are so great. Coming soon

wlandau commented 4 years ago

@jennybc, I know it has been over a month, but https://github.com/ropensci-org/community-calls/issues/5#issuecomment-574874270 really helped me get started on a spec for drake: https://books.ropensci.org/drake/design.html. Thank you.

Bisaloo commented 4 years ago

Not entirely sure if this is on topic but a recurring question for me is: how to encourage and facilitate user feedback? Users sometimes notice bugs or suboptimal behaviours (either relating to performance or user experience) but they don't often report them because they're not sure how / don't feel confident enough to do so(?)

The BugReports field is filled but it doesn't seem to be enough.

stefaniebutland commented 4 years ago

Hi @Bisaloo. I'm not a panelist, but I think it's on topic :-)

I'm in the starting stage of developing a community contributing guide for rOpenSci and your question hits a key element at the interface of users and developers. I'd love for the guide to help package authors get the input they want, the way they want to receive it, and for users to be confident in the ways they can give feedback.

Thanks so much for noting that here.

peterdesmet commented 4 years ago

@Bisaloo @stefaniebutland I created a CONTRIBUTING.md template for R packages, that is organized from easy to difficult contributions, hoping it convinces (especially new) users that every kind of contribution helps: https://gist.github.com/peterdesmet/e90a1b0dc17af6c12daf6e8b2f044e7c

@stefaniebutland maybe it's also useful for the community contributing guide you're starting?

stefaniebutland commented 4 years ago

This is wonderful @peterdesmet. I've added it to my list of great examples to consult.

embruna commented 4 years ago

Hi all, as a novice who had to deal with an issue almost as soon as our package went live, I can't wait for this call...thanks for this.

I'd like to hear advice on thinking ahead to maintenance when still in the package development phase. What shapes decisions about relying on a package to do something instead of coding it from scratch? If opting for relying on a package, how does one chose among the potential options to include as a dependency? What best practices will make maintenance easier down the road? Etc.

stefaniebutland commented 4 years ago

This morning our panel had a pre-event meeting to discuss questions and their perspectives. It's going to be good!

We use a shared google doc during Community Calls and I think this one will be a great opportunity for participants to add their own perspectives in the doc for others to see.

ddsjoberg commented 4 years ago

Is there space we can submit topics for discussion?

Something I have found to be increasingly frustrating is the minimum R version supported. I have a few packages in Suggests: I use in my unit tests only. For example, I want to ensure proper behavior of my package functions when using cubic splines from the {Hmisc} package. {Hmisc} depends on {latticeExtra}, which is a min R version requirement of 3.6. What is the best practice for ensuring continued support for older R versions when dependencies of dependencies of dependencies keep upping the minimum version of R required (and in this case, for a dep I only use in unit tests). Currently using Travis CI to test on various versions of R.

Thank you! Looking forward to the call! https://github.com/ddsjoberg/gtsummary

stefaniebutland commented 4 years ago

@ddsjoberg You asked in the right place. With 4 panelists + 1 moderator doing Q&A we won't have time for audience questions this time.

However!

I will encourage participants (you!) to add their questions to our shared google doc so that other participants, and maybe the panelists, might answer in the doc. That doc will be shared permanently at https://ropensci.org/commcalls/2020-03-18/ after the call.

stefaniebutland commented 4 years ago

Video of this Community Call panel Q & A on Maintaining an R Package is up, plus links to collaborative notes and resources: https://ropensci.org/commcalls/2020-03-18/.

Thanks to all of you for attending, taking notes, asking and answering questions!

stefaniebutland commented 4 years ago

ropensci-org / community-calls

Maintaining a package #5

Who is the audience?

Why is this important?

What should be covered?

Suggested speakers or contributors

Resources you would recommend to the audience