Skip to content

Open Liberty Conventions

Jump to bottom
Eric Covener edited this page Jul 18, 2024 · 11 revisions

In addition to knowing the basic guidelines of contributing, there are some conventions and processes in use by the OpenLiberty project that are helpful to know for working in the repository.

Issues

Issues are intended to be the embodiment of the data related to a problem or intended change. The issue lifecycle covers from when the need for a change is found, up through when it's verified to have been completed.

Pull Requests

Pull requests are generally complementary to issues, but sometimes a pull request can stand alone if it's a trivial change or a change not related to a user visible issue. Care should be taken if a Pull Request is not accompanied by an associated issue that the change is either trivial, certainly standalone, or doesn't have a visible failure or problem scenario. Imagine the case where that Pull Request either proves to be incomplete, or has to be reverted. Would that Pull Request still make sense if someone comes back to it later if it exists out on its own?

Linking Issues and Pull Requests should be done via text in the Pull Request (e.g. Fixes #12345) rather than manually linking via the Development widget in the interface. The former is scraped by some tools that do not currently understand the latter.

If a known issue (including IBM APARs) for a distribution of Open Liberty is related to a Pull Request, we suggest linking it in a similar fashion with a Fixes #knownissue-identifier in a comment or description.

Release bugs

A particularly important class of issues are those reporting problems in released code. These are important since they describe problems that could be encountered by a user with a stable driver. If a particular issue is being reported because it was seen in a full release (like 17.0.0.4, 18.0.0.1, etc. Not a nightly driver) OR if it can be verified that a user with a full release could encounter the problem, then this is a bug in released code or a "release bug". Accordingly, these should be labelled as a "release bug" for further documentation.

While all issues should be descriptive, with these especially it should include:

  • Version of the server the problem was encountered
  • Instructions to reproduce
  • Any error messages or stacks relevant to the issue
  • If there's a known workaround

Reasoning

At each full release (17.0.0.4, 18.0.0.1, etc.) we'll in the future keep a listing of fixed item in the release. To do this, automation has to figure out:

  1. A problem existed in released code
  2. What code (PRs) were used to fix the problem
  3. That the problem was fixed

In practice, this is worked from the code delivery backwards by:

  1. Seeing a PR merged into the stream using the key "Merge pull request #XXXX". This is the definitive text we use to notice a chunk of code was delivered
  2. Searching the PR for Issue mentions to verify if the PR was standalone or not
  3. Looking at each mentioned issue to see if a "release bug" label exists, if it does this is to be considered a Release Bug
  4. If the issue and is closed, this is a completed Release Bug and will go into the notes (todo) of that release as being a potential user-visible bug that's been fixed.

The integration stream

Steps the Developer needs to take

  1. Associate issue number in the PR by Fixes #<issueNumber> (or fixed, closes, closed)
  2. Make sure the issue has release bug tag
  3. State of the issue must be closed in order to be picked up by the Fixlist Tool.
Clone this wiki locally