Return-Path: 
 <dev-return-31658-apmail-poi-dev-archive=poi.apache.org@poi.apache.org>
X-Original-To: apmail-poi-dev-archive@www.apache.org
Delivered-To: apmail-poi-dev-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 99382188D9
	for <apmail-poi-dev-archive@www.apache.org>;
 Wed, 25 Nov 2015 09:57:31 +0000 (UTC)
Received: (qmail 49894 invoked by uid 500); 25 Nov 2015 09:57:31 -0000
Delivered-To: apmail-poi-dev-archive@poi.apache.org
Received: (qmail 49858 invoked by uid 500); 25 Nov 2015 09:57:31 -0000
Mailing-List: contact dev-help@poi.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@poi.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@poi.apache.org>
List-Post: <mailto:dev@poi.apache.org>
List-Id: <dev.poi.apache.org>
Reply-To: "POI Developers List" <dev@poi.apache.org>
Delivered-To: mailing list dev@poi.apache.org
Received: (qmail 49839 invoked by uid 99); 25 Nov 2015 09:57:31 -0000
Received: from Unknown (HELO spamd1-us-west.apache.org) (209.188.14.142)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 25 Nov 2015 09:57:31 +0000
Received: from localhost (localhost [127.0.0.1])
	by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org)
 with ESMTP id C36FAC3CFA
	for <dev@poi.apache.org>; Wed, 25 Nov 2015 09:57:30 +0000 (UTC)
X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org
X-Spam-Flag: NO
X-Spam-Score: 2.1
X-Spam-Level: **
X-Spam-Status: No, score=2.1 tagged_above=-999 required=6.31
	tests=[KAM_COUK=1.1, KAM_LAZY_DOMAIN_SECURITY=1] autolearn=disabled
Received: from mx1-us-east.apache.org ([10.40.0.8])
	by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new,
 port 10024)
	with ESMTP id ClQT7betIOxq for <dev@poi.apache.org>;
	Wed, 25 Nov 2015 09:57:30 +0000 (UTC)
Received: from mx.corefiling.com (mx-aa.corefiling.com [90.155.100.37])
	by mx1-us-east.apache.org (ASF Mail Server at mx1-us-east.apache.org) with
 ESMTPS id D5930428E7
	for <dev@poi.apache.org>; Wed, 25 Nov 2015 09:57:29 +0000 (UTC)
Received: from router.int.corefiling.com ([10.0.0.1]:58827 helo=[10.0.0.5])
	by smtp.corefiling.com ([10.0.0.141]:587)
	with esmtpsa (ldap_plain:dtn) (TLSv1.2:DHE-RSA-AES128-SHA:128)
	id 1a1WpF-0000tC-SD (Exim 4.84)
	(return-path <dtn-poi@corefiling.co.uk>); Wed, 25 Nov 2015 09:57:21 +0000
Subject: Re: deprecated handling - reloaded
To: POI Developers List <dev@poi.apache.org>
References: <56550453.7030407@apache.org>
 <CAM+Tpp+w8a0bu6vTtT0=hCUWm8TEe1TFCSr_1B08a-rXqhUm7g@mail.gmail.com>
From: David North <dtn-poi@corefiling.co.uk>
X-Enigmail-Draft-Status: N1110
Message-ID: <56558606.7070608@corefiling.co.uk>
Date: Wed, 25 Nov 2015 09:57:26 +0000
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.3.0
MIME-Version: 1.0
In-Reply-To: 
 <CAM+Tpp+w8a0bu6vTtT0=hCUWm8TEe1TFCSr_1B08a-rXqhUm7g@mail.gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
X-SystemFilter: not expanding corefiling.co.uk

On 25/11/15 06:40, Javen O'Neal wrote:
> Tldr:
> Here's what I propose:
> 1) contributors should add dates and/or POI versions to @deprecated
> annotations for new commits
> 2) contributors should add @since version annotations to new features
> 3) new features may be removed without deprecation only if added prior to a
> final build and removed before or during the next final build (same release
> series)
Makes sense to me.
> ...
> Can we automatically check for `@deprecated <release version or date>` or
> `@since <release version>` in Jenkins?

That's crucial in my view: we've got to have automated enforcement that
this kind of metadata is being kept accurate and acted upon, otherwise
it will rapidly become an out of date embarassement.

A bit of Googling doesn't come up with any obvious tools for inspecting
the deprecated tag in JavaDoc, however if we did something like this:-

* Use the @Deprecated annotation in addition to the JavaDoc tag (which
is useful for some IDEs anyway)
* Invent our own @Removal annodation to contain the date/POI version of
expected removal

Then it would be easy to write a functional test which used reflection
to check all @Deprecated annotated elements had an @Removal too, and to
tell us when things come up as due to be removed.

David

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org