I'm planning to go with a short NOTES entry in man pages like so:

diff --git a/iptables/arptables-nft-restore.8 b/iptables/arptables-nft-restore.8
index 09d9082cf9fd3..1bc5572754f66 100644
--- a/iptables/arptables-nft-restore.8
+++ b/iptables/arptables-nft-restore.8
@@ -32,6 +32,8 @@ Use I/O redirection provided by your shell to read from a file
 .TP
 .B arptables-restore
 flushes (deletes) all previous contents of the respective ARP Table.
+.SH NOTES
+This tool is deprecated, new setups should use nftables instead.
 .SH AUTHOR
 Jesper Dangaard Brouer <brouer>
 .SH SEE ALSO

I'll do this for the following man pages:

iptables/arptables-nft-restore.8
iptables/arptables-nft-save.8
iptables/arptables-nft.8
iptables/ebtables-nft.8
iptables/iptables-apply.8.in
iptables/iptables-restore.8.in
iptables/iptables-save.8.in
iptables/iptables.8.in
iptables/xtables-legacy.8
iptables/xtables-monitor.8.in
iptables/xtables-nft.8

What do you say, is this sufficient? I thought about linking to a migration howto, but am hesitant to put long URLs into man pages. Here are some examples:

- https://wiki.nftables.org/wiki-nftables/index.php/Main_Page#Upgrading_from_xtables_to_nftables
- https://developers.redhat.com/blog/2017/01/10/migrating-my-iptables-setup-to-nftables
- https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_networking/getting-started-with-nftables_configuring-and-managing-networking#assembly_migrating-from-iptables-to-nftables_getting-started-with-nftables

(In reply to Phil Sutter from comment #1)
> I'm planning to go with a short NOTES entry in man pages like so:
> 
> diff --git a/iptables/arptables-nft-restore.8
> b/iptables/arptables-nft-restore.8
> index 09d9082cf9fd3..1bc5572754f66 100644
> --- a/iptables/arptables-nft-restore.8
> +++ b/iptables/arptables-nft-restore.8
> @@ -32,6 +32,8 @@ Use I/O redirection provided by your shell to read from a
> file
>  .TP
>  .B arptables-restore
>  flushes (deletes) all previous contents of the respective ARP Table.
> +.SH NOTES
> +This tool is deprecated, new setups should use nftables instead.

I would like it to be a little for assertive.

"This tool is deprecated. It is maintenance only and will not receive new features. New setups should use nftables. Existing setups should migrate to nftables when possible."

>  .SH AUTHOR
>  Jesper Dangaard Brouer <brouer>
>  .SH SEE ALSO
> 
> I'll do this for the following man pages:
> 
> iptables/arptables-nft-restore.8
> iptables/arptables-nft-save.8
> iptables/arptables-nft.8
> iptables/ebtables-nft.8
> iptables/iptables-apply.8.in
> iptables/iptables-restore.8.in
> iptables/iptables-save.8.in
> iptables/iptables.8.in
> iptables/xtables-legacy.8
> iptables/xtables-monitor.8.in
> iptables/xtables-nft.8
> 
> What do you say, is this sufficient? I thought about linking to a migration
> howto, but am hesitant to put long URLs into man pages. Here are some
> examples:

Agreed. Lets avoid the URLs. We'll need an access article about the deprecation. That's a good place to point to migration tutorials/howtos.

For iptables you can suggest iptables-translate.

(In reply to Phil Sutter from comment #1)
> I'm planning to go with a short NOTES entry in man pages like so:

> @@ -32,6 +32,8 @@ Use I/O redirection provided by your shell to read from a
> file
>  .TP
>  .B arptables-restore
>  flushes (deletes) all previous contents of the respective ARP Table.
> +.SH NOTES
> +This tool is deprecated, new setups should use nftables instead.
>  .SH AUTHOR
>  Jesper Dangaard Brouer <brouer>
>  .SH SEE ALSO

> What do you say, is this sufficient?

I think so, plus a nft(8) reference.

I'm leaning towards the shorter note, as we will need to reach out to
the users/customers through other channels (and in more detail) as well,
anyway, but I'll defer to your and Eric's judgement.

Is this intended as a downstream change? Wouldn't it make more sense
upstream first/as well, given that the position there is the same?

(In reply to Štěpán Němec from comment #3)
> (In reply to Phil Sutter from comment #1)
> > I'm planning to go with a short NOTES entry in man pages like so:
> 
> > @@ -32,6 +32,8 @@ Use I/O redirection provided by your shell to read from a
> > file
> >  .TP
> >  .B arptables-restore
> >  flushes (deletes) all previous contents of the respective ARP Table.
> > +.SH NOTES
> > +This tool is deprecated, new setups should use nftables instead.
> >  .SH AUTHOR
> >  Jesper Dangaard Brouer <brouer>
> >  .SH SEE ALSO
> 
> > What do you say, is this sufficient?
> 
> I think so, plus a nft(8) reference.
> 
> I'm leaning towards the shorter note, as we will need to reach out to
> the users/customers through other channels (and in more detail) as well,
> anyway, but I'll defer to your and Eric's judgement.

I like Eric's version. I added references to *-translate tools where sensible,
let's see if I can integrate that nft(8) reference as well without blowing
things up too much.

And I agree with the assessment of this being not sufficient on it's own no
matter how elaborate we make it.

> Is this intended as a downstream change? Wouldn't it make more sense
> upstream first/as well, given that the position there is the same?

Downstream only, upstream doesn't like calling iptables "deprecated", at least
not yet.

Taking a step back here:

- Deprecation notice should go first in DESCRIPTION, not hidden in a NOTES section
- Add a shortened URL for further reading
- Refer to nft(8) (and where sensible, iptables-translate) in SEE ALSO section
- Drop deprecation notices from xtables-nft/xtables-legacy man pages, they describe the concepts not commands