Introducing changes to EWP APIs

In this section of the documentation we describe a procedure for introducing changes to EWP specifications. When working on changes to some of the specifications we found it necessary to more strictly set the sequence of steps leading to stable versions of specifications.

A developer creates a pull request for a set of changes.

Rules for Accepting API Change Proposals are described in GitHub - erasmus-without-paper/ewp-specs-management at v1.2.1 .

Note: A pull request is a proposal to merge a set of changes from one branch into another. Pull requests facilitate discussion around code changes. Developers can comment on the changes, suggest improvements, and ask questions before the new code is merged. This collaborative process leads to higher quality code.

Note: The name “pull request” comes from the idea that you're requesting the project to “pull” changes from your fork. You initiate a pull request when you're ready to begin merging new changes in the code to the project's main repository. You're informing the rest of the project team about your intentions.

Developers have time for comments which may result in changes to a pull request.

After the set timeframe and discussing the comments the proposed changes are merged to the main branch and announced as RC (Release Candidate). This is a signal for developers to start implementing changes in the DEV network. Note: The RC version is an invitation for development and testing within the DEV network. It is not yet a final, stable version.

If developers encounter problems during implementation and new changes are needed, the process returns to Step 1. Implementation issues that do not require changes are discussed on an ongoing basis.

When there are working implementations in the DEV network, the changes are issued as an official stable new version. This is a signal that working implementations can be installed in PROD. Note: The stable version is released only after the DEV tests are completed. The RC version is for testing (which can reveal various issues) and the stable version is for production use.

Only trivial changes of already implemented APIs may be released without previously asking for the review of the other partners.

It should be emphasized that the presented procedure concerns strictly technical aspects of developing a stable version of the specification and cause-effect relationships between presenting developers with technical details of the proposed changes (in the form of a pull request), collecting and discussing comments (in the context of the presented technical solutions), presenting changes to the specification in a form ready for implementation (in the DEV environment, and after developing a stable version of the specification in the PROD environment). The subject of this procedure is not the process of creating change proposals from the business side, the decision-making process of choosing between alternative technical solutions, the mode and place of conducting discussions with developers (IF meetings, workshops, Jira, GitHub or any other), nor the duration of individual iterations or their number.