From 3f2de3470b22a22af9a3e418b71b2d3a1196dc53 Mon Sep 17 00:00:00 2001 From: Jeen Broekstra Date: Sun, 13 Nov 2022 16:02:14 +1300 Subject: [PATCH] GH-4237 reorg and update of developer docs --- CONTRIBUTING.md | 5 +- .../documentation/developer/releases.md | 16 +++--- .../documentation/developer/workflow.md | 50 +++---------------- 3 files changed, 14 insertions(+), 57 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cc033ed2f1..e88f693cd60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,7 +53,7 @@ Once the legalities are out of the way you can dig in. Here's how: 7. Commit your changes into the branch. Make sure the commit author name and e-mail correspond to what you used to sign the ECA. Use meaningful commit messages. Reference the issue number in the commit message (for example "GH-276: added null check"). 8. Push your changes to your branch in your forked repository. 9. Optionally [squash your commits](https://rdf4j.org/documentation/developer/squashing) to clean up the commit history. -10. Use GitHub to submit a pull request (PR) for your contribution back to `main` in the central RDF4J repository. Once you have submitted your PR, do not use your branch for any other development (unless asked to do so by the reviewers of your PR). +10. Use GitHub to submit a pull request (PR) for your contribution back to the central RDF4J repository. Once you have submitted your PR, do not use your branch for any other development (unless asked to do so by the reviewers of your PR). Once you've put up a PR, we will review your contribution, possibly make some suggestions for improvements, and once everything is complete it will be merged into the `main` branch (if it's a bug fix to be included in the next maintenance release) or into the `develop` branch (if it's a feature or improvement to be included in the next minor or major release). @@ -66,6 +66,7 @@ Eclipse RDF4J follows the [Eclipse Coding Conventions for Java](https://wiki.ecl - We use a line width of 120 characters. - We use Unix line endings (LF). - We require curly braces for every control statement body (e.g. if-else), even if it is a single line. +- We use a single tab as the indentation in all XML files (including the `pom.xml` files). - We use the following header comment on every Java file: ``` @@ -98,8 +99,6 @@ For import statements, the following conventions hold: There are various ways to apply these conventions to your code, depending on which editor/IDE you use. -We use a single tab as the indentation in all XML files (including the `pom.xml` files). - ### Eclipse IDE users 1. In Eclipse, open 'Preferences' -> 'Java' -> 'Code Style' -> 'Formatter' diff --git a/site/content/documentation/developer/releases.md b/site/content/documentation/developer/releases.md index c7ffc718dbb..ac941f3c92c 100644 --- a/site/content/documentation/developer/releases.md +++ b/site/content/documentation/developer/releases.md @@ -175,15 +175,15 @@ upload, it will also automatically invoke synchronization with the Central Repository. Note that after successful completion, the artifacts may not be available on the Central Repository for several hours. -## Minor and Major releases +## Eclipse release reviews -Minor and major releases require a formal [release review](https://www.eclipse.org/projects/handbook/#release-review), and because this is the case, they need to be planned well in advance, and the project lead needs to manage what can go into each release, and prepare necessary documentation (both technical and legal) for review. +At least once a year, the Eclipse Foundation requires a formal [release review](https://www.eclipse.org/projects/handbook/#release-review). We typically try to use a major or minor release for such a review. -We plan each release about 8 weeks in advance. At this stage, the final feature set is not etched in stone but a number of priority features/improvements is identified (via discussion on the mailinglist and/or via issue tracker comments and PRs) and scheduled. A first draft of a release plan is created by the project lead on the [Eclipse RDF4J project site](https://projects.eclipse.org/projects/technology.rdf4j), and the necessary milestones are created in the [issue tracker](https://github.com/eclipse/rdf4j/issues). +We plan a reviewed release about 8 weeks in advance. At this stage, the final feature set is not etched in stone but a number of priority features/improvements is identified (via discussion on the mailinglist and/or via issue tracker comments and PRs) and scheduled. A first draft of a release plan is created by the project lead on the [Eclipse RDF4J project site](https://projects.eclipse.org/projects/technology.rdf4j), and the necessary milestones are created in the [issue tracker](https://github.com/eclipse/rdf4j/issues). ### Review planning and application -A release can only be done once its review is successfully concluded. Eclipse release review are announced in regular cycles, and always complete on the first or third Wednesday of each month. For this reason, we schedule our releases to happen on a first or third Thursday. +Eclipse release review are announced in regular cycles, and always complete on the first or third Wednesday of each month. For this reason, we schedule our reviewed releases to happen on a first or third Thursday. A release review runs for a week. Although mostly a formality, it does need some careful preparation and planning. It needs to be formally applied for, and this application in turn requires that several pieces of documentation are in order: @@ -212,16 +212,13 @@ For more detailed information about the release review process, see the [Eclipse ### Branching minor releases Prior to a minor release, the `develop` branch is merged into the `main` branch -(along with the `develop` branch's version) to facilitate release review. -This will increment the `main` version to the latest major/minor SNAPSHOT version. -After the review is complete the steps to create a minor release are the same as the patch release steps. +(along with the `develop` branch's version). This will increment the `main` version to the latest major/minor SNAPSHOT version. IMPORTANT: It is important that only features and fixes that have already been scheduled for release (via PR milestone labels) be merged into the `develop` branch, so that there is no confusion as to what will be included in the next minor release. -Once a minor release is published the `develop` minor version should be incremented to the next SNAPSHOT -version and any approved features that are scheduled for this next minor +Once a minor release is published the `develop` minor version should be incremented to the next SNAPSHOT version and any approved features that are scheduled for this next minor version should be merged into `develop` branch. ## Optional: publish a docker image @@ -249,7 +246,6 @@ Push the image: Note that hub.docker.com does not update the `latest` tag automatically, the newly created image has also to be tagged `latest` and pushed to hub.docker.com. - ### Method 2: multi-platform docker image using buildx Since the base image being used is available for multiple architectures, diff --git a/site/content/documentation/developer/workflow.md b/site/content/documentation/developer/workflow.md index dcc64290604..f15597b0ca6 100644 --- a/site/content/documentation/developer/workflow.md +++ b/site/content/documentation/developer/workflow.md @@ -14,17 +14,16 @@ Some of this information is targeted specifically at the project lead(s), other RDF4J strives to apply [Semantic Versioning](http://www.semver.org/) principles to its development: 1. We use a `MAJOR.MINOR.PATCH` versioning template. -2. A *PATCH* release (2.2.1, 2.2.2, etc.) is a release that contains only bug fixes that are backwards compatible. -3. A *MINOR* release (2.0.0, 2.1.0, 2.2.0, etc.) is a release that can contain improvements and new features but makes no backward-incompatible changes to existing functionality. -4. A *MAJOR* release (1.0.0, 2.0.0, 3.0.0, etc) is a release that can contain changes to the public API that are not backward compatible. +2. A *PATCH* release (2.2.1, 2.2.2, etc.) is a release that contains only bug fixes that are binary compatible and source compatible. +3. A *MINOR* release (2.0.0, 2.1.0, 2.2.0, etc.) is a release that can contain improvements and new features but makes no binary-incompatible changes to existing functionality. +4. A *MAJOR* release (1.0.0, 2.0.0, 3.0.0, etc) is a release that can contain changes to the public API that are not compatible. -It is currently not fully specified what the boundaries of the RDF4J public API are. Until this is resolved (see [issue #619](https://github.com/eclipse/rdf4j/issues/619)), we allow changes to public or protected methods/classes/interfaces in *minor* releases under the following conditions: +We allow changes to public or protected methods/classes/interfaces in *minor* releases under the following conditions: 1. any renamed _interface_ is declared an extension of the old interface. The old interface is marked deprecated with Javadoc containing a reference to the new name; 2. any renamed _class_ is declared a superclass of the old class. The old class is marked deprecated with Javadoc containing a reference to the new name; 3. any renamed _member_ is added next to the old member name. The old member is declared deprecated with Javadoc containing a reference to the new name. - -These conditions are to ensure that existing user code will continue to work when upgrading to the new release. If there is any doubt about a change being backwards-compatible, it can not be made part of a minor release. +4. any class, interface or method that is annotated with `@Experimental` or `@InternalUseOnly` is not considered part of the public API, and may be changed in a minor release. For patch releases we never allow changes in the public API, unless the change is specifically to fix a bug that aligns the actual behavior of the code with the publicly documented behavior. @@ -68,44 +67,7 @@ achieve a clean but accurate history. Read more about our strategy and the motivation for it in this article: [RDF4J merge strategy](/documentation/developer/merge-strategy/). -### Patch Requests - -If the change is a bug fix, contains no new features, and does not change any public or protected APIs: - -1. Create an issue in our [issue tracker](https://github.com/eclipse/rdf4j/issues) if it doesn't exist yet. -1. Create an issue branch by branching off from the `main` branch, using `GH--short-description` as the branch name convention. -2. Make the necessary changes and verify the codebase. -3. Optionally [squash your commits](../squashing) to clean up your branch. -3. Create a Pull Request that targets the `main` branch. -4. Peers and project committers now have a chance to review the PR and make suggestions. -5. Any modifications can be made to the _issue_ branch as recommended. -6. Once any necessary changes have been made, project committers can mark the PR as approved. -7. Project committers should then determine what patch release this fix will be included in by updating the milestone label of both the PR and the issue. -8. Once a Pull Request is approved and scheduled, it can be merged into the `main` branch. -9. After a PR has been merged into the `main` branch, the `main` branch should -then be merged into the `develop` branch by the project committer that merged the PR, any conflicts (such as due to new features) should be resolved. - -### Feature Requests - -Pull Requests that add a self-contained new feature to the public API follow -the same steps as a Patch Request but should target the `develop` branch. -Only PRs that have been scheduled for the next minor release -should be merged into the `develop` branch. - -Project committers that are contributing to a branch should periodically -pull changes from the `develop` branch (by either rebasing or merging) to minimize conflicts later on. -Once a feature is complete a PR should be created using the feature branch and target the `develop` branch. -Then follow similar steps to a patch request to schedule and merge into `develop`. - -Minor and major releases require a formal [release -review](https://www.eclipse.org/projects/handbook/#release-review), and because -this is the case, they need to be planned well in advance, and the project lead -needs to manage what can go into each release, and prepare necessary -documentation (both technical and legal) for review. For this reason approved -Pull Requests may stay open (not scheduled or merged) for some time until a -release plan that incorporates these changes and any required documentation is -in place. The comment section in the PR can be used to keep everyone informed -of the progress. +For step-by-step instructions on how to create contributions, see the [contributor guidelines](https://github.com/eclipse/rdf4j/blob/main/CONTRIBUTING.md). ## Further reading