001/*
002 * ============================================================================
003 *  Copyright © 2002-2026 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.annotation;
019
020import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
021import static java.lang.annotation.ElementType.CONSTRUCTOR;
022import static java.lang.annotation.ElementType.FIELD;
023import static java.lang.annotation.ElementType.LOCAL_VARIABLE;
024import static java.lang.annotation.ElementType.METHOD;
025import static java.lang.annotation.ElementType.MODULE;
026import static java.lang.annotation.ElementType.PACKAGE;
027import static java.lang.annotation.ElementType.PARAMETER;
028import static java.lang.annotation.ElementType.RECORD_COMPONENT;
029import static java.lang.annotation.ElementType.TYPE;
030import static java.lang.annotation.ElementType.TYPE_PARAMETER;
031import static java.lang.annotation.ElementType.TYPE_USE;
032import static java.lang.annotation.RetentionPolicy.RUNTIME;
033import static org.apiguardian.api.API.Status.STABLE;
034
035import java.lang.annotation.Repeatable;
036import java.lang.annotation.Retention;
037import java.lang.annotation.Target;
038
039import org.apiguardian.api.API;
040
041/**
042 *  <p>{@summary This annotation allows to add information about applied fixes
043 *  (aka. &quot;Change Requests&quot;) to a program element.}</p>
044 *  <p>This annotation does not appear in the Javadoc documentation of the
045 *  annotated program elements.</p>
046 *
047 *  @author Thomas Thrien - thomas.thrien@tquadrat.org
048 *  @version $Id: CR.java 1294 2026-10-17 15:40:42Z tquadrat $
049 *  @since 0.25.14
050 *
051 *  @UMLGraph.link
052 */
053@SuppressWarnings( "NewClassNamingConvention" )
054@ClassVersion( sourceVersion = "$Id: CR.java 1294 2026-10-17 15:40:42Z tquadrat $" )
055@API( status = STABLE, since = "0.25.14" )
056@Retention( RUNTIME )
057@Target( {ANNOTATION_TYPE, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, MODULE, PACKAGE, PARAMETER, RECORD_COMPONENT, TYPE, TYPE_PARAMETER, TYPE_USE} )
058@Repeatable( ChangeRequestList.class )
059public @interface CR
060{
061        /*---------------*\
062    ====** Inner Classes **====================================================
063        \*---------------*/
064    /**
065     *  <p>{@summary Types of change requests.}</p>
066     *
067     *  @author Thomas Thrien - thomas.thrien@tquadrat.org
068     *  @version $Id: CR.java 1294 2026-10-17 15:40:42Z tquadrat $
069     *  @since 0.25.14
070     *
071     *  @UMLGraph.link
072     */
073    @ClassVersion( sourceVersion = "$Id: CR.java 1294 2026-10-17 15:40:42Z tquadrat $" )
074    @API( status = STABLE, since = "0.25.14" )
075    public enum CRType
076    {
077        /**
078         *  <p>{@summary The implementation of a generic change request.}</p>
079         */
080        @SuppressWarnings( "FieldNamingConvention" )
081        CR,
082
083        /**
084         *  <p>{@summary A bug fix.}</p>
085         */
086        @SuppressWarnings( "FieldNamingConvention" )
087        BUG,
088
089        /**
090         *  <p>{@summary A patch for debugging purposes; perhaps only temporary.}</p>
091         */
092        DEBUG,
093
094        /**
095         *  <p>{@summary The implementation of an enhancement request.}</p>
096         */
097        @SuppressWarnings( "FieldNamingConvention" )
098        ENH,
099
100        /**
101         *  <p>{@summary A field service patch.}</p>
102         */
103        @SuppressWarnings( "FieldNamingConvention" )
104        FSP,
105
106        /**
107         *  <p>{@summary A maintenance patch.}</p>
108         */
109        PATCH,
110
111        /**
112         *  <p>{@summary A change that was required by a new version of the
113         *  product.} Use this type if there is no change request id for this
114         *  particular change. Use the new version as the
115         *  {@linkplain #id() id}.</p>
116         */
117    }
118    //  enum CRType
119
120        /*------------*\
121    ====** Attributes **=======================================================
122        \*------------*/
123    /**
124     *  <p>{@summary An optional comment regarding the change.}</p>
125     *
126     *  @return The comment.
127     */
128    String comment() default "";
129
130    /**
131     *  <p>{@summary The date when the change was applied, in the format
132     *  &quot;YYYY-mm-dd&quot;.} Will be ignored if empty.</p>
133     *
134     *  @return The change date.
135     *
136     *  @see java.util.Formatter
137     */
138    String date() default "";
139
140    /**
141     *  <p>{@summary The id for the change request as provided by the
142     *  respective tracking system.}</p>
143     *
144     *  @return The change request id.
145     */
146    @SuppressWarnings( "NewMethodNamingConvention" )
147    String id();
148
149    /**
150     *  <p>{@summary The type for the change request.}</p>
151     *
152     *  @return The type of the change request.
153     */
154    CRType type() default CRType.CR;
155}
156//  @interface BUG
157
158/*
159 *  End of File
160 */