RFC: Adopt a new project name

[pastelmind]

Timeline

• Apr 25: I started a forum thread on kolmafia.us, so people without GitHub accounts can join in the conversation.
• May 02: I started a poll for the new name (Google Forms, requires login). It will be closed by May 7th (Sat) 06:00 AM UTC.
• May 12: Poll was closed. You can view the results below, or by visiting the poll page.

Overview

We have received requests to move away from the current name ("OCD-Cleanup") to support non-ableist language. "OCD-Cleanup" inherits the name from OCD Inventory Control, from which it was forked.

We expect non-trivial challenges in renaming this project. However, we may gain some benefits. Thus, I'd like to request for comments in this article.

Edit: I created a forum thread on https://kolmafia.us/threads/thoughts-on-renaming-ocd-cleanup.26002 so that people can voice their sentiments without creating a GitHub account.

Technical Challenges

If we rename this project, it makes sense to rename the primary script (ocd-cleanup.ash) and relay script (relay_OCD-Cleanup_Manager.ash) as well. If we use different names for the project and the scripts, users may be confused, especially when debugging the script and reporting issues. Furthermore, keeping the old name around would undermine the agenda for renaming the project.

Renaming the project and the scripts will cause breaking changes, which we should address carefully:

• Changes to the install/update URL
  • No immediate action required: GitHub provides transparent redirects for renamed repositories. These redirects last indefinitely. This means that existing installs won't break unless someone creates a new project named "OCD-Cleanup" within our organization.
  • Nevertheless, some action is required to make bug reporting & troubleshooting easier. Users should uninstall the project and reinstall via the new URL.
  • We can programmatically detect installed packages by name (see svn_exists()). We can therefore emit warnings to users who haven't reinstalled yet, and provide appropriate instructions.
• Changes to script names:
  • At best, this adds minor cognitive overhead to users who need to remember the new names.
  • At worst, it forces users to change aliases and rewrite import statements in their scripts.
  • We have precedent for this. Shortly after forking, we renamed our files (see #9) to allow this project to be installed side-by-side with OCD Inventory Control. Anyone who has migrated from OCD Inventory Control to this project is likely aware of what they need to do.
  • We can provide shims for the old script names scripts during a transitory period (let's say 3 months, or however long it takes to migrate the rest of the project).
  • The shims could issue non-intrusive warnings (let's say once per day) to nudge users to use the new script names

Opportunity for Changes

Renaming the project provides a unique opportunity to add breaking changes:

• Migrate cleanup script to JavaScript/TypeScript
  • Most importantly, JavaScript scripts can accept an arbitrary number of command-line arguments. We can support UNIX-style command line options using libraries like minimist.
  • JavaScript/TypeScript is is more maintainable than ASH in the long term, due to having a greater developer pool, better development tools, and more educational materials.
• Increase awareness of the project
  • Despite having existed for several months, our project does not have a separate thread on http://kolmafia.us/. Moving away from the "OCD" name provides an opportunity to introduce this project to a larger audience. Edit: Forum megathread is up!
  • A new project name communicates that this project is ready to make backwards-incompatible decisions and move in a different direction than OCD Inventory Control.
• Increase awareness of new Manager
  • I've been working on a new Manager frontend to replace the current relay script. Renaming the project provides an apt opportunity to showcase the new UI.

Rename to What?

Members of the KoLmafia forums and the Ascension Speed Society Discord have suggested the following names (in alphabetical order): Declutter, Dematerializer, Invensorty, InventoryCleanup, InventoryManagement, Philter, TidyJS, Script That Follows The Rules, InvClean.

I hosted an anonymous poll between May 02 and May 12. Each participant were given two votes, including an option to suggest a name other than those in the list. 28 people participated including myself. The results are still viewable by visiting the poll link, but I'll copy-paste them here for convenience:

Poll results (2021-05-12) [click to show/hide]

 | Name | Votes | % | |--------|------:|------:| | Declutter | 5 | 17.9% | | Dematerializer | 1 | 3.6% | | Invensorty | 7 | 25.0% | | InventoryCleanup | 11 | 39.3% | | InventoryManagement | 4 | 14.3% | | **Philter** | **15** | **53.6%** | | TidyJS | 2 | 7.1% | | Script That Follows The Rules | 1 | 3.6% | | InvClean | 1 | 3.6% | In addition, one person gave a vote for "OCD-Cleanup". I assume they preferred to keep the current name?

"Philter" has been selected by a significant (53.6%) number of participants. 🎉 Thank you to everyone who joined in the poll!

When does this happen?

Note: Technical details are being moved to #43.

Phase 1: Preparation

• Apr 24 - May 01: Gather feedback on initial proposal and draw rough plan
• May 02 - May 12: Host a poll for a new name
• May 12: Add detailed plans

Phase 2: Migration

Expect 3~4 weeks.

• Repository URL changes
  • Rename the repository
  • Rename files and directories that do not affect users
  • Rename monorepo scope (@ocd-cleanup → @philter)
  • Update documentation and write migration guide
  • Make cleanup script detect install URL and emit warnings (once/day)
• New manager UI
  • Rename both old and new relay scripts, since they probably won't impact user workflows. 🤞
  • Update messages: Remove poll link, add link to user migration guide?
• New cleanup script
  • Add new cleanup script, written in TypeScript
  • Load data files with new prefixes?
• Other concerns
  • Should we change the ruleset file prefixes (OCDdata_, OCDstock_)?
  • Should we rename the ZLib settings?
  • Should we "transparently" 🤔 maintain backwards compatibility? Or should we provide a "migration script" that users can run once to rename files and config vars?

Phase 3: Touchdown

Expect ~3 months, which should give users ample time to adapt.

• Repository URL changes
  • Hopefully, no changes needed for this
• New manager UI
  • Add missing features from OCD-Cleanup Manager
  • Investigate ways to improve developer experience
  • Investigate ways to improve user experience
  • Move to beta status
  • Add highly requested features, if any
  • Deprecate, then remove old Manager UI
• New cleanup script
  • Rewrite core in TypeScript
  • Make the old script (ocd-cleanup.ash) a thin wrapper for the core
  • Challenge: ASH scripts cannot import JavaScript code directly, and must rely on cli_execute(). How can we wrap around this issue?
  • Challenge: Some users import ASH functions directly from ocd-cleanup.ash. We should support this use case by exposing ASH functions from another file (not ocd-cleanup.ash).

Trivia

Trivia

_("RFC" stands for [Request for Comments](https://en.wikipedia.org/wiki/Request_for_Comments). It refers to a formal process of sharing ideas and proposals, and is popular among many organizations. We don't have any such formal practices, though; I just thought it sounded good.)_

[taltamir]

requests? as in more than one person? really? at first I thought this was a prank but on second thought I can imagine this being real in todays world. this is not a trivial change either as it requires every single user out there to manually uninstall and then reinstall to get the new names. personally I am against causing such a massive hassle for so many people over such a thing if it really gets renamed then I am in favor of invClean. mostly because it is short

[pastelmind]

I didn't want to name names because I understand it might be a polarizing subject--some may feel incredulous, others passionate. The idea came up in Discord, though, so you can locate the original conversation if need be.

[Rinn]

If this ends up happening I'd also use it as an opportunity to change the primary branch from 'master' to 'release' or something like that.

[pastelmind]

Are you recommending that we keep a master branch for code and release branch for build artifacts? While I like that approach (single source of truth and whatnot), it needs more effort than just renaming the repo. We can no longer rely on GitHub's redirects to push updates seamlessly to existing users. We'd have to figure out a different migration strategy.

(I'm not saying "no" here ofc. It may still happen but we need to discuss it more.)

Even if that happens, I believe making the release branch the primary one is a bad idea. Since GitHub displays the primary branch to visitors, we need a proper README to act as the "home page", providing instructions for installing, usage, etc. However, we can't put a README in the release branch.

[Rinn]

No i mean get rid of master entirely because it's also construed as problematic.

You can have a readme in the release branch if you move the mafia files into a subfolder like autoscend does.

[pastelmind]

Oh, ok. In that case I say let's go with main as it's what GitHub is recommending anyway. Better to align with the expectations of newcomers who would be more familair with main.

Edit: It's done.

[Crotha]

As long as the migration process is written for people who can barely make github accounts, I am all for it!
Get your own name and recognition 👍

ETA: https://github.com/Loathing-Associates-Scripting-Society/OCD-Cleanup/pull/38
couldn't this alpha be used for the namechange and introduction? Or is the intention of OCD2 something different (because above a rewrite due to the namechange is listed as pro, and the alpha sounds like a rewrite, just of a larger scale)

[pastelmind]

I put up a forum thread over at kolmafia.us (link also added above). We could keep the more technical discussion here.

38 is not a full rewrite (yet). It is a rewrite for the relay script which is the web page part. The cleanup script which does the actual cleanup is still ASH.

I've been postponing a full rewrite because I could not justify breaking backwards compatibility before. Now that we actually have something we can advertise as a major upgrade, I might look into it again.

[taltamir]

Well, if this goes through the only less painful way I can see it working is: step 1: fork the code. step 2: rename the fork step 3: the original should not be deleted. instead an update should be pushed to abort on run which instructs people to uninstall current version and install the differently named one

this will minimize the pain of the rename if it goes through.

[pastelmind]

Aborting on run would be disruptive; I'd like to add a transitory period where we emit deprecation warnings. Assuming that people run the cleanup at least once per month, I think we can put the warnings up for 2~4 weeks.

Renaming the repository itself is not disruptful, at least immediately. GitHub provides transparent redirects so that installs using the current URL would "just work". Just to be sure, I tried installing via the old URL we used before the first rename, and it still works:

svn checkout http://github.com/Loathing-Associates-Scripting-Society/OCD-Inventory-Control/trunk/release

(We can't delete the redirect either, since GitHub controls the whole thing. But why bother?)

My idea is to detect the install URL used via svn_exists() and emit instructions for reinstall.

---

Renaming the scripts would take more involvement. Here's a rough plan:

1. Introduce new scripts that wrap the existing scripts. New scripts will have to coexist with the old ones for a period of time.
2. Move the core logic into new scripts, and convert the old scripts into wrappers for the new scripts. The situation has turned.
3. Add deprecation warnings to old scripts so that users see what is going on.
4. After a grace period of 2-4 weeks, remove the old scripts.

[Phillammon]

I'm happy to out myself as one of the voices advocating for a rename, and back many of the suggestions here. Pastel's above plan makes a lot of sense, and it would appear that github's transparent redirects obviate the most egregious downsides, which is nice.

As to the actual naming question, I'd like to second both philter and invClean as respectively in keeping with tradition and being a direct explanation of what the script does, so either seems worthwhile on that front.

[pastelmind]

Here's the poll for the name change. I'll leave it open until Saturday. Yup, I knew I'd miss my own deadlines 😭.

[pastelmind]

Poll results are up! See the Rename to What? section of the first post. Thanks to everyone who participated.

I also added more detailed plans in the When does this happen? section. The plan may change, or be moved into a separate tracking issue(s).