I know what should be done first

At this stage, there is only re-order with drag'n drop. Reorder with "arrow-up" and "arrow-down" (like in Planning view) is not supported.

I can reorder:

• In backlog
• Inside a Program Increment
• while assigning a Feature to a Program Increment
• while moving a Feature from a Program Increment to another Program Increment
• while moving back a Feature from a Program Increment to Backlog

REST routes to be added, they will follow the same pattern than the route used in agiledashboard The PATCH route depends on prioritization permission

We need to update the route GET projects/{id}/program_backlog and GET program_increment/{id}/content to make them return ordered collections

Changing priority of an element will be done with PATCH /projects/{id}/program_backlog will be updated

Another new REST route will be added: PATCH program_increment/{id}/content. It will also be called when planning features in a Program Increment and will replace the existing call to PUT artifacts/{id}

following payload will be supported :

{
   "order":{
      "ids":[
         123
      ],
      "direction":"before",
      "compared_to":456
   },
   "add":[
      {
         "id":123
      }
   ]
}

123 is added to PI it is added before feature 456

Planning and un-planning of features in Program Increments

Given a Feature already planned in PI A, if I move it by planning it in PI B, the REST route will have to identify that it is planned in PI A and un-plan it from PI A before planning it in PI B.

For such un-planning cases, the following rule must be respected:

If at least one User Story linked from the Feature is already planned in an Iteration (e.g. a Sprint) in one of the Teams, then the Feature can no longer be un-planned. In such a case, the REST route must return an error explaining to the user why the Feature cannot be un-planned.

Existing code does not respect this rule and must be changed to enforce it (instead of allowing Feature un-planning and leaving some User Stories planned).

Multiple drag and drop

"Multiple drag and drop" of features, for example selecting feature 123 and 456 and 789 and dropping them in a PI or reordering them in the top backlog, is not supported. It is not requested and our current drag and drop library does not offer it natively. The REST route technically accepts a list of feature ids to reorder or to plan in a PI in order to be future-proof. But given that "multiple drag and drop" is not supported by the frontend, the REST route will return an error code if more than one feature is given in the payload.

For example:

{"add": [{"id": 123}, {"id": 456}] }

// or

{"order": {"ids": [123, 456],  "direction":"before", "compared_to": 789 } }

The two payloads above are technically correct but will be rejected with an error code in order to simplify the backend logic, given that the frontend is not capable of producing such payloads yet anyway.

During the work on this story, we experimented with trying "design reviews". The idea is that instead of writing all the code first and then doing code review once everything is split into classes and objects, we sat down and tried to write a plan of how we would write the code. We wrote it in plain French (as we communicate in French) but I'll translate it here for an example. Please keep in mind that code has changed since then, some classes have been renamed, etc.

Plan of how to implement the REST route to add features in a Program Increment PATCH program_increment/$id/content

1. Retrieve a PI with the given $id using the interface RetrieveProgramIncrement
2. Send an error if no PI matching $id exists. Code 404
3. Send an error if the current user can't see the PI. Code 404
4. Retrieve the Program of the PI. Code to be written with interface SearchProgram
5. Send an error if it can't be found. Code 404
6. Check current user has prioritize permissions with PrioritizeFeaturesPermissionVerifier. Transform returned false into error code 403
7. If there is more than one feature in the "add" payload, send an error Code 400
8. Retrieve the feature matching the id in the "add" payload.
   1. send an error (code 400) if the given id does not exist
   2. send an error (code 400) if the given id is not a feature. Check that it matches an artifact whose Tracker can be planned in the Plan linked to the given PI.
   3. send an error (code 400) if the current user can't see the feature.
   4. Retrieve an object FeatureIdentifier with the given id. Code / SQL query to be written
9. Start an SQL transaction
10. Search if the Feature is already planned in a PI.
11. If that is the case:
    1. Search if at least one User Story linked to this Feature has already been planned in an Iteration (in a Team)
    2. If that is the case, send an error code 400
    3. If not, remove the feature from that PI (un-plan it).
12. Remove the feature from the Top Backlog
13. Modify the artifact link of the PI to add the given feature. We need to add it to the list of existing artifact links and create a new tracker Changeset. With ArtifactLinkUpdater ? A bit like MilestoneElementMover
14. End SQL transaction
15. Test manually that the new changeset will trigger the hook to replicate planification (plan User Stories linked to the Feature) in Mirrored Milestones.

This plan captures roughly what has been done just to "add" a feature to a Program Increment. Sharing it with other developers helped raise missing points, for example we had first forgotten to check if the Feature was visible for the current user. It also provided opportunity for other developers to point out existing code for certain bullet points, thus avoiding to write them a second time.