[Evergreen-dev] New devs onboarding: discussion items for Tuesday

[Jason Stephenson]

I started a reply on June 9, but decided to put it off.  I deleted that 
draft and started over almost a week later.  This draft has sat in my 
drafts folder for a while.  I've finally decided to "finish" it.

On 6/9/23 12:25, Stephanie Leary via Evergreen-dev wrote:
> Happy Friday, everyone! I have a series of items on Tuesday's developer 
> meeting agenda relating to the new developer onboarding experience, as I 
> mentioned briefly in my lightning talk at the conference. I went to jot 
> down my thoughts, and when my Google doc hit its third page, I thought 
> perhaps I should send this out ahead of the meeting to give everyone 
> time to digest.
> 
> We have at least two organizations looking to hire Evergreen developers, 
> and I know of a third that might be posting something in the near 
> future, so this seems like a good time to talk about what it's like to 
> join this project without previous experience in this community.
> 
> *Wiki organization*
> 
> At the conference, I asked everyone to look at the wiki home page, 
> pretending that you are a newcomer. Some questions I think the wiki home 
> page should answer:
> * What is Evergreen?
> * What does it take (broadly speaking) to install and manage Evergreen?
> * Where do I go for discussion about Evergreen?
> 
> I think it's pretty hard to answer all of these on the current wiki home 
> page. (For fun, search this page for the word "library.") It would be 
> fine to copy some things from the docs; I will note that “Evergreen 
> End-user Documentation” is a bullet point halfway down the wiki home 
> page with no elaboration.

Kathy Lussier has already mentioned that the basic questions were 
intended to be answered by the main website and not the wiki.

That said, the wiki is embarrassing. I agree with pretty much everything 
Stephanie says below, except that I think a lot of the old stuff ought 
to be tossed and not archived.  I wonder if it would be better to start 
over with a fresh wiki and import the things we want to keep, such as 
the new developers documentation?

I believe the wiki has gotten into the state that it is in because there 
are only so many of us, and our time is already spent on other things 
related to Evergreen.

I think we could do well to have a similar push for more complete 
documentation as well.

> 
> Old stuff needs to be moved out of the way and clearly marked as 
> archival or of historical interest.
> 
> The code/language page is seriously intimidating, and needs to be 
> rewritten so that it is clearer which languages are necessary to work on 
> specific parts of Evergreen: the OPAC, the newer staff interfaces, and 
> sysadmin tasks all have different requirements. A newcomer needs to be 
> reassured that they do not have to be masters at ten different 
> languages. 
> https://wiki.evergreen-ils.org/doku.php?id=newdevs:landscape:code 
> <https://wiki.evergreen-ils.org/doku.php?id=newdevs:landscape:code>
> 
> The New Devs sidebar has an outline of the developer documentation we 
> are working on; it would be great to have contributions from not-new 
> devs: https://wiki.evergreen-ils.org/doku.php?id=newdevs:start 
> <https://wiki.evergreen-ils.org/doku.php?id=newdevs:start>
> 
> *IRC channel findability*
> 
> IRC is a barrier to entry for newer developers. I know there is a Gen X 
> nostalgia factor here, but we need to seriously consider moving to 
> Slack. It would be great to have channels for each of the interest 
> groups, for example.

I disagree with moving to Slack.  As a F/OSS project, we should eschew 
proprietary means of communication.  Slack being a proprietary product, 
I will avoid it if I can.

I am also bothered by the push to create new "mailing lists" as Google 
Groups.  I don't say much because were are a small project with limited 
resources, and we don't have the people to manage everything ourselves.

I am not a F/OSS absolutist.  I do use proprietary software or platforms 
when the trade off seems worth it.  I do have a preference for F/OSS 
solutions.

Along similar lines, since doing the gitolite upgrade and migration to a 
new virtual machine for the community, I have cooled on moving our code 
to GitHub, Gitlab, or some other hosting service, particularly one 
running proprietary software.  Again, it's a bad look.

> 
> Even if we stay in IRC, there is an issue with the visibility of 
> channels other than #evergreen itself. I did not know there was a 
> separate channel for release discussions until Andrea mentioned it a 
> while back. I still cannot find it in the server channel list–is it 
> unlisted?–and as far as I can tell there is no mention of it in the wiki.

The release discussions would rarely be interesting to anyone other than 
those participating in the releases.  It is mostly about coordinating 
who does what, and not about how we do what.

Security releases also require an additional level of coordination that 
often happens more in private to prevent the leak of potentially 
exploitable information before the fixes are publicly available.

> 
> Obviously I could have asked for its name at any time, but I wanted to 
> make a point of going through the 3.11 release without it, just to see 
> what that was like. Here’s how things went down from my point of view:
> 
> *  A couple of months ago there was a call for more participation in the 
> release cycle.
> * Bugs got targeted for 3.11, work got done, things got discussed in 
> #evergreen.
> * Then the conversation in #evergreen went DEAD SILENT for two weeks.
> * 3.11 appeared as if by magic.
> * Conversation in #evergreen slowly resumed.

At the development meeting on June 13, it was proposed to remove the 
'secret' flag from the channel so it would show up in channel lists.  It 
was also proposed to eliminate the #evergreen-release channel and have 
all of the discussion in #evergreen.  I am OK with either move.

> 
> I have absolutely no idea how a new developer is supposed to learn about 
> the release process or get involved in it.

Well, there's a wiki page that details the release steps, but to be 
honest, I don't know how a new developer would get involved right away, 
either.  (To be honest, I still don't think I understand the 
translations process.)


> 
> I would like to ask someone to take on the job of laying breadcrumbs 
> from the wiki home page to some documentation about how releases happen 
> and where that discussion is taking place.

Some of that has been done since Stephanie's original email.  I also 
just found a new (to me) page about the release notes process on the 
wiki while searching for something else this morning.

I wonder if it would be useful for the new devs group to work on 
organizing the wiki since the new devs "area" is already pretty well 
organized?


> 
> *Inline documentation*
> 
> The lack of inline documentation is a serious problem for new 
> developers. I have really struggled to figure out how data gets into big 
> display components like eg-tree and eg-grid. It’s also hard to figure 
> out which modules need to be included to make various things happen.
> 
> I think we need to pick an inline documentation style, dump some empty 
> boilerplates at the top of every custom module, and start filling things 
> in as we can. I know of ngDoc, but there might be other good candidates. 
> https://medium.com/@askoropad/ngdoc-documentation-for-angular-projects-3f6ea8fc22b0 <https://medium.com/@askoropad/ngdoc-documentation-for-angular-projects-3f6ea8fc22b0>
> 
> Some object references in the wiki would also be very helpful, 
> especially anywhere the word “fleshing” appears.
> 
> *Code standards*
> 
> https://wiki.evergreen-ils.org/doku.php?id=code_formatting_standards 
> <https://wiki.evergreen-ils.org/doku.php?id=code_formatting_standards> 
> is a little sparse. Are there parts of 
> https://github.com/airbnb/javascript 
> <https://github.com/airbnb/javascript> or some other well-established 
> standard that we want to reference or borrow?

A million times coding standards and inline documentation!  There should 
also be stronger requirements for automated tests, particularly for new 
features. We have evolved past the point of "works for me."

OpenSRF and Evergreen are also more than just JavaScript.  There is a 
lot of C and Perl as well as Bash and SQL.

I'm going to go way beyond this topic in another email that was 
originally part of this one.  I think it would be more appropriate to 
tack my other thoughts onto the thread about Rust.


> 
> *VSCode*
> 
> Many of our experienced developers are command line warriors. Respect! 
> However, a lot of our newer developers use VSCode, and we need more 
> guidance on how to set up the project workspace and which files can 
> safely be ignored.
> 
> VSCode is free and available for Linux as well as Windows and Mac, so it 
> would be great if we could get a few more experienced developers to 
> experiment with it and help out with some setup documentation. The New 
> Devs group has a suggested list of extensions here: 
> https://wiki.evergreen-ils.org/doku.php?id=newdevs:landscape:tools 
> <https://wiki.evergreen-ils.org/doku.php?id=newdevs:landscape:tools>

I have no issue with individuals in the community helping those who use 
a particular editor and making wiki pages about it.  If this is a 
semi-official thing, it would make sense to add information about the 
other "popular" editors in the community: vim, GNU Emacs, or whatever 
editor someone is interested in promoting.  I don't think any particular 
tool should be singled out as special unless it is integral to working 
with our project/code, such as git for instance.

> 
> *In summary*
> 
> Evergreen is an especially complicated and opaque project. It's 
> extraordinarily difficult to join without having some kind of prior 
> experience in the community. I know everyone is stretched thin, but 
> helping new developers figure out how things work is going to help us 
> all distribute the workload more evenly in the long run.
> 
> I will be happy to talk more about this on Tuesday and to partner with 
> anyone who wants to take on some of the to-do items I've described. (As 
> long as it's after the ALA conference.)

I agree. It takes a long time to get used to things, particularly if 
you're not focused on building the code or setting up your own server. 
It took me a year, or more, of fiddling around before I was comfortable 
submitting patches back in the day, and I still learn new things about 
Evergreen and OpenSRF all the time.

Based on the minimal discussion in the developers' meeting, this is not 
a situation that we're going to fix overnight.  It's good that we're 
having a discussion and hopefully can make some progress toward being 
less opaque.

Cheers,
Jason Stephenson