Ticket #1751 (closed todo: fixed)

Opened 4 years ago

Last modified 4 years ago

Links to DEPRECATED.pod et al

Reported by: Paul C. Anagnostopoulos Owned by: jkeenan
Priority: normal Milestone:
Component: docs Version: 2.6.0
Severity: medium Keywords:
Cc: cotto, Coke, dukeleto Language:
Patch status: Platform:

Description

The Support Policy wiki page contains three links to DEPRECATED.pod, all of which are broken. It also contains two mentions of the ParrotDeprecations page, neither of which are linked. It does not mention the Deprecation or ParrotDeprecationsForx.y pages.

The main wiki page mentions DEPRECATED.pod without a link and also contains a link to the Deprecation page. It does not mention the ParrotDeprecation or ParrotDeprecationForx.y pages.

Confusing? You betcha. Let's at least link to all pages from each of those pages, with some rationale for the multiplicity. Better yet, do we really need to list deprecations in four places?

Change History

  Changed 4 years ago by jkeenan

  • status changed from new to assigned
  • owner set to jkeenan

Paul:

Agreed, this was confusing me just this morning.

Let's take this in steps.

1. The two wiki pages that most closely resemble one another are: Deprecation and ParrotDeprecations.

The latter is newer and seems to reflect current policy better than the former. Would you be willing to examine the former and see what content can be transferred to the latter? We could then deactivate the former page and link the wiki Main Page to the latter.

2. I have redirected the link you cited to the Support Policy on HowToDeprecate to the  appropriate page on the main Parrot web site. I believe these pages get regenerated once a month after the monthly release.

3. Could you review what I've done so far and suggest next steps?

Thank you very much.

kid51

follow-up: ↓ 4   Changed 4 years ago by Paul C. Anagnostopoulos

I'd go a little more radical. I'd merge all three wiki pages into one page giving a complete description of each deprecation by version. I'd link to that on the main wiki page and on the Support Policy page. The long-timers may have a reason for multiple pages, but I can't imagine what it is.

I'd change DEPRECATED.pod so it simply refers to the wiki page. If that seems dangerous because people can edit the wiki page too easily, then have it contain an exact copy of the wiki page.

Is it possible to make the wiki page part of the source and install it after each official build? If so, then that would solve the wiki versus DEPRECATED.pod duplication.

  Changed 4 years ago by Paul C. Anagnostopoulos

To answer my own question, CPAN has pod2wiki.

One master file of deprecations, DEPRECATED.pod, converted to a wiki page on each build and installed as the deprecations wiki page. Everything in exactly one place.

in reply to: ↑ 2   Changed 4 years ago by jkeenan

  • cc cotto, Coke added

Replying to Paul C. Anagnostopoulos:

I'd go a little more radical.

Well, note that I recommended proceeding step-wise. It may ultimately prove beneficial to merge all those pages into one. But let's first get a single page that describes what has been deprecated when, and get other people's reactions to that.

I'd change DEPRECATED.pod so it simply refers to the wiki page.

[snip]>

Is it possible to make the wiki page part of the source and install it after each official build? If so, then that would solve the wiki versus DEPRECATED.pod duplication.

I believe DEPRECATED.pod should remain the official source for what is scheduled for deprecation. In part, this is for historical continuity: I think most of our core developers think first in terms of going to the source code and only secondarily of going to the wiki.

(kid51 is more skeptical than others of the usefulness of wikis. I've found them useful when preparing for events to be held at a specific point in time, such as YAPCs and F2F hackathons. I find them less useful for ongoing project documentation for reasons very similar to those which generated this ticket: Wikis sprawl. Individual pages are not kept up-to-date. Links are not kept up-to-date. And you spend a lot of time typing formatting instructions and previewing pages -- a lot more keystrokes than simply typing in source code files. But setting my personal opinions aside ...)

So I'd like first to see what content from Deprecation can be moved over to ParrotDeprecations. Then we should here from other committers, particularly from people who have been more involved in setting up these pages than I have, e.g., cotto and Coke.

Thank you very much.

kid51

  Changed 4 years ago by Paul C. Anagnostopoulos

But if DEPRECATED.pod can be converted to a wiki page, we have the best of all possible worlds. It remains the official repository of deprecation information, in its current pod format. It's part of the source, so developers see it. Then we convert it to a wiki on each build and install it in the wiki tree. The three existing wiki pages disappear, to be replaced by this one page generated from the official file. To summarize:

DEPRECATED.pod is the official repository of all deprecation information, in full detail, by version.

The three existing wiki pages disappear.

ParrotDeprecations is generated from DEPRECATED.pod on each build and installed in the wiki tree. It is linked from the main wiki page and from the Support Policy page.

  Changed 4 years ago by Paul C. Anagnostopoulos

Getting from here to there in multiple steps is, of course, just fine.

  Changed 4 years ago by coke

First off, on the original post, there's a mention of a support policy wiki page, but no url. I don't see this page.

The proposed solution really seems like overkill to me. Let me back up and summarize the goals with the information.

1) provide a notification to our users with a shipped release about upcoming removals due to deprecated items.

2) provide a way for users of old versions to migrate their code to work on new versions.

It would be nice if #1 was in the release. It would be nice if #2 was not, but was in the wiki.

Having a single file in the repository with EVERY compatibility change ever (going forward) seems like overkill to me, ESPECIALLY if we then duplicate it on the wiki (it would already be generated by "make html" and therefore on docs.parrot.org.)

I don't see what the argument against multiple pages is. We clearly want it segregated by parrot version; I think for our users, multiple pages (1 per version) with an index page linking to each of them is the best approach. They are only going to care about certain items.

Paul - what problem are you trying to solve with your proposed changes?

  Changed 4 years ago by Paul C. Anagnostopoulos

Sorry, I said wiki page but the Support Policy page is HTML:  http://docs.parrot.org/parrot/latest/html/docs/project/support_policy.pod.html. Notice that it has three dead links to DEPRECATED.pod. Those need to be fixed.

Now we also mention DECPRECATED.pod on the main wiki page:  http://trac.parrot.org/parrot/wiki. There is no link to it. Later on the page we have a link to the ParrotDeprecations page, but not to the ParrotDeprecationsForx.y pages.

I disagree that one file with all deprecations is overkill. It seems like the minimalist approach to me. If they are in reverse order by version, a person doesn't have to read any further than they care to. That file, DEPRECATED.pod, is converted to HTML during the build, as you say. Then it would be linked from both the Support Policy page and the main wiki page. One source file, one target file, two links.

If you really think that one page per version, with a table of contents page, is the way to go, I can be persuaded. The table of contents page would be linked on the Support Policy and main wiki pages. Then we would have a .pod file for the contents and one .pod file for each version, right? But we would also have the information duplicated in DEPRECATED.pod, which wouldn't even be linked anywhere. That's annoying.

Could we possibly organize DEPRECATED.pod with a table of contents at the top and then a section for each version? Then a person could simply click on the desired version and ignore the rest of the file.

Problem I am trying to solve: It's not good to have deprecation information in more than one source file. (When I was adding deprecation information for a change, there was no way I was going to find all the files I was supposed to edit without having it explained to me. And even then I couldn't find ParrotDeprecationsFor2.6)

  Changed 4 years ago by jkeenan

  • cc dukeleto added

Friends,

I suspect that this TT might be obsolete now that we have a spiffy new YAML-ish way to store our deprecations.

Do you agree?

cc-ing some additional suspects.

Thank you very much.

kid51

  Changed 4 years ago by jkeenan

At the very least, this wiki page, ParrotDeprecations, needs updating, as it leaves off at changes between 2.9 and 3.0.

  Changed 4 years ago by dukeleto

  • status changed from assigned to closed
  • resolution set to fixed

I updated the wiki page and added a section for deps between 3.0 and 3.3. We have api.yaml now. If there are specific issues with that, open a new ticket.

Updated link on main wiki page to to api.yaml on Github.

Note: See TracTickets for help on using tickets.