Simplified workflow for removing internals from base

[adamgundry]

I see there have been a recent flurry of tickets from @bgamari proposing removal of internals, which in many cases have a response from @hasufell indicating a deprecation period is in order. In the interests of saving everyone's time and expediting the cleanup process, perhaps we could agree a standard workflow for deprecation and removal of internal modules or definitions, that would apply to such tickets?

This could be something like:

• A CLC proposal ticket identifies the modules/definitions to be removed, and invokes this standard workflow. No MR is required at this stage.
• The CLC considers and votes on the removal proposal. If it is rejected, the workflow stops.
• Haddock comments (and DEPRECATED pragmas?) are added to the affected modules/definitions in the next major release of base, documenting that they are scheduled for removal.
• In any subsequent release major release of base, such modules/definitions can be removed by GHC developers without further approval from CLC (though obviously if there is a reason to reverse the previous decision, e.g. due to feedback from users during the deprecation window, this can be brought to the attention of the GHC devs).

We can debate the details, but the key point is to separate the decision-making stage (for which CLC oversight is required) from the execution of that decision (which happens over time, without need for further input from the CLC). Moreover, by following a standard script it should be clearer to everyone involved that "removal" means "removal after a deprecation period".

Of course, if in particular cases this workflow is not appropriate, then the usual processes can still be used. Does this seem reasonable?

[bgamari]

Thanks for writing this, @adamgundry. I agree that establishing a clear, consistent workflow will better for all involved.

[hasufell]

I propose

Deprecation period

1. morally internal GHC modules that have less than 50 users on hackage need a deprecation period of at least 6 months
2. morally internal GHC modules that have more than 50 users on hackage need a deprecation period of at least 1 year
3. morally internal GHC modules that have more than 200 users on hackage need a deprecation period of at least 2 years
4. if the module contains potentially wildly generic functions such as (>>>), the deprecation period may be increased by at least a year

Deprecation comments

Deprecation comments should be verbose:

1. what is the planned last GHC version that will allow to import this module
2. explain migration strategy (different module, different package, different functions...)
3. if there is no migration possible, explain why

Process remarks

1. CLC members may raise concerns for specific functions, saying "we actually want those in base". The CLC has the obligation to propose a new home for those functions (which module exactly).
2. The proposer shall update the status of all proposals here: https://docs.google.com/spreadsheets/d/1WmyYLbJIMk9Q-vK4No5qvKIIdIZwhhFFlw6iVWd1xNQ/edit#gid=1315971213 outlining the deprecation statuses and CLC proposals
3. Proposals may be batched, e.g. by:
   • domain (e.g. all of GHC.Stack.*)
   • by hackage users (few hackage users indicates it's easier to vote yes) or deprecation period
   • by how "internal" they are perceived
4. if a batch proposal fails, it's fine to split it into multiple... the process may still help to streamline the work, because we already got some non-binding opinions etc.. One proposal per module seems insane to me.

[bgamari]

I am fine with this general framework. I will go ahead and close this as I think that this ticket has served its purpose.

[simonpj]

There are some conclusions from this thread... Adam suggested a workflow, Julian made some additions. It would to collect the agreed process in one place, so we can then follow it. (A closed issue isn't a good place.)

Where would be a good place?

[bgamari]

Yes, that is a fair point. One option would be to add the process as an addendum to the "Combining Stability with Innovation" proposal.

[simonpj]

One option would be to add the process as an addendum to the "Combining Stability with Innovation" proposal.

Yes that would be great.

We could also add this: https://github.com/simonpj/hf-tech-proposals/blob/ghc-module-naming-2023/proposals/0000-ghc-module-naming.rst , which is otherwise in danger of getting lost.

Who would like to do the secretarial work? It probably would not take long. I know how stretched you are Ben, but could you imagine doing that? Or Adam?

[adamgundry]

I'm happy to write something up. Given that this is mainly about CLC process, and it is ultimately for the CLC to decide, perhaps a document in this repo would make sense?

[adamgundry]

I've opened #223 to try to address this.

I incorporated most of @hasufell's text above, except for this:

2. The proposer shall update the status of all proposals here: https://docs.google.com/spreadsheets/d/1WmyYLbJIMk9Q-vK4No5qvKIIdIZwhhFFlw6iVWd1xNQ/edit#gid=1315971213 outlining the deprecation statuses and CLC proposals

I suggest making the deprecation process open to public collaboration, rather than exclusively covering requests from the GHC Team. Thus I'm not convinced it makes sense to designate this particular spreadsheet for tracking such proposals. I can imagine it might be useful to have some kind of tracking in addition to the GitHub issues, both for deprecation and for other proposals, but I'm not really in a position to suggest how that might work.

[hasufell]

I suggest making the deprecation process open to public collaboration

It is open to public, but I would expect GHC HQ to maintain that spreadsheet regardless. I don't see how that would contradict?

[adamgundry]

I suggest making the deprecation process open to public collaboration

It is open to public, but I would expect GHC HQ to maintain that spreadsheet regardless. I don't see how that would contradict?

Perhaps you might like to suggest a patch to #223 that explains what you have in mind? I'm still struggling to see how to integrate such an expectation into the process as described there.

[bgamari]

Ping @hasufell. To be clear, I'm not necessarily opposed to maintaining the spreadsheet

[Bodigrim]

@adamgundry if you want to move forward with this, could you possibly reflect on my comments at https://github.com/haskell/core-libraries-committee/pull/223#issuecomment-2190034625?

[Bodigrim]

I understand from #223 that this is withdrawn, please correct me if I'm wrong.