[struts-site] 09/09: Converts new pages related to creating distro

[lu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lukaszlenart pushed a commit to branch contributors-guide
in repository https://gitbox.apache.org/repos/asf/struts-site.git

commit 160cb672248e21b8cbebdf03af45af8f4c9ce76b
Author: Lukasz Lenart <lu...@apache.org>
AuthorDate: Tue Sep 29 09:07:10 2020 +0200

    Converts new pages related to creating distro
---
 source/contributors/building-struts-master.md      | 112 +++++++++++++++++++++
 .../creating-and-signing-a-distribution.md         |   2 +-
 source/contributors/index.md                       |   7 +-
 source/contributors/obtaining-an-idea-license.md   |  29 ++++++
 source/contributors/one-time-steps.md              |   2 +-
 source/contributors/precise-error-reporting.md     |  31 ++++++
 6 files changed, 177 insertions(+), 6 deletions(-)

diff --git a/source/contributors/building-struts-master.md b/source/contributors/building-struts-master.md
new file mode 100644
index 0000000..d1a60f9
--- /dev/null
+++ b/source/contributors/building-struts-master.md
@@ -0,0 +1,112 @@
+---
+layout: default
+title: Building Struts Master
+parent:
+  title: Contributors Guide
+  url: index.html
+---
+
+# Building Struts Master
+{:.no_toc}
+
+* Will be replaced with the ToC, excluding a header
+{:toc}
+
+## Building Steps (Struts)
+
+### Obtain a fresh checkout
+
+```
+git clone https://gitbox.apache.org/repos/asf/struts-master.git
+```
+
+### Change site target
+
+Apply needed changes, in most cases it will be upgrade to the latest Apache Parent POM, eg. from 9 to 10,
+commit the change.
+
+### Prepare release
+
+Tag the release by using the "release:prepare" goal of Maven: 
+
+```
+mvn release:prepare -DautoVersionSubmodules=true
+```
+
+For a [dry run](http://maven.apache.org/plugins/maven-release-plugin/usage.html), add `-DdryRun=true`. If you do a dry run,
+use `mvn release:clean` to clean up after you have looked at the output. 
+
+When prompted for the SCM tag name, follow this pattern: `STRUTS_MASTER_[PATCH_VERSION]`
+
+If for some reason, the release plugin might fail to tag the release, if it fails, run:
+
+```
+mvn release:prepare -Dresume 
+```
+
+This step will ([more information](http://maven.apache.org/plugins/maven-release-plugin/examples/prepare-release.html)):
+
+- Check that there are no uncommitted changes in the sources
+- Check that there are no SNAPSHOT dependencies
+- Change the version in the poms from x-SNAPSHOT to a new version (you will be prompted for the versions to use)
+- Transform the SCM information in the POM to include the final destination of the tag
+- Run the project tests against the modified POMs to confirm everything is in working order
+- Commit the modified POMs
+- Tag the code in the SCM with a version name (this will be prompted for)
+- Bump the version in the POMs to a new value y-SNAPSHOT (these values will also be prompted for)
+- Commit the modified POMs
+
+### Perform the release
+
+```
+mvn release:perform
+```
+
+This step will ([more information](http://maven.apache.org/plugins/maven-release-plugin/examples/perform-release.html)):
+
+- Checkout from an SCM URL with optional tag
+- Run the predefined Maven goals to release the project (by default, deploy site-deploy)
+
+After this step the artifacts will be hosted by [Nexus](http://repository.apache.org/)
+
+If you need to run perform again, (or in a different box), do:
+
+```
+git co tags/$VERSION
+mvn deploy site-deploy --no-plugin-updates -DperformRelease=true 
+```
+
+Next, log in to [Nexus](http://repository.apache.org/) and **close** staging repository.
+
+### Announce availability
+
+Send a short e-mail to `dev@struts.a.o` informing about the new packages and to give people enough time to test 
+the distribution (actual bits). Wait around a week before posting Vote. If no show-stoppers reported, start a vote 
+thread for build quality designation.
+
+The new build is available from staging repository: `https://repository.apache.org/content/groups/staging/org/apache/struts/struts-master/[PATCH_VERSION]/`
+
+### Vote on it
+
+Post a release/quality vote to the dev list (and **only** the dev list). The example mail is on [Sample Announcements](sample-announcements) page. 
+
+If the vote result is for an ASF release (i.e. not test build), update site, announce. If the vote result is for GA, push to central.
+
+### Promote release
+
+Log in again to [Nexus](http://repository.apache.org/) and **release** the repository, it will be automatically replicated across Maven Repositories
+
+See [Releasing a Maven-based project](http://maven.apache.org/developers/release/apache-release.html) for further details.
+
+### Wait for rsync
+
+Wait 2-6 hours before proceeding. 
+
+### Post announcements
+
+We leave this as the last step, once the artifacts have had time to sync up on the mirrors. Target it to:
+
+- user@struts.a.o
+- announcements@struts.a.o
+ 
+samples are available at [Sample announcements](sample-announcements) page.
diff --git a/source/contributors/creating-and-signing-a-distribution.md b/source/contributors/creating-and-signing-a-distribution.md
index 0957667..a50d744 100644
--- a/source/contributors/creating-and-signing-a-distribution.md
+++ b/source/contributors/creating-and-signing-a-distribution.md
@@ -31,7 +31,7 @@ Depends on what you want to achieve, please select topic from the list below:
 
 - [One time steps](one-time-steps) - before you start preparing a distribution
 - [Sample announcements](sample-announcements) - announcements used to communicate the achievement
-- [Building Struts Master](#PAGE_27839549) - how to release Struts Master
+- [Building Struts Master](building-struts-master) - how to release Struts Master
 - [Building Struts Annotations](#PAGE_27832965) - when you want to prepare a new distribution of Struts Annotations (if something changed)
 - [Building Struts 2 - Normal release](#PAGE_27832970) - the most common used path
 - [Building Struts 2 - Fast track release](#PAGE_27834014) - how to prepare a fast track release with important security patch
diff --git a/source/contributors/index.md b/source/contributors/index.md
index fa24924..049602d 100644
--- a/source/contributors/index.md
+++ b/source/contributors/index.md
@@ -9,10 +9,9 @@ title: Contributors Guide
 
 - [Building the Framework from Source](building-the-framework-from-source)
   - [Building with Maven](building-with-maven)
-- [Creating and Signing a Distribution](creating-and-signing-a-distribution)
-- [Requirements](#PAGE_29362) and [Use Cases](#PAGE_29364) - _under construction_ 
-- [Precise Error Reporting](#PAGE_29826)
-- [Obtaining an IDEA license](#PAGE_29381)
+- [Creating and Signing a Distribution](creating-and-signing-a-distribution) 
+- [Precise Error Reporting](precise-error-reporting)
+- [Obtaining an IDEA license](obtaining-an-idea-license)
 - [How to Write Doc Comments for the Javadoc Tool](http://java.sun.com/j2se/javadoc/writingdoccomments/) (Sun)
 
 ## Documentation
diff --git a/source/contributors/obtaining-an-idea-license.md b/source/contributors/obtaining-an-idea-license.md
new file mode 100644
index 0000000..539e661
--- /dev/null
+++ b/source/contributors/obtaining-an-idea-license.md
@@ -0,0 +1,29 @@
+---
+layout: default
+title: Obtaining an IDEA license
+parent:
+  title: Contributors Guide
+  url: index.html
+---
+
+# Obtaining an IDEA license
+{:.no_toc}
+
+* Will be replaced with the ToC, excluding a header
+{:toc}
+
+## How do ASF Committers obtain an IDEA license?
+
+Please read the following blog post about JetBrains support for Apache - [JetBrains Supports the Apache Software Foundation](https://blog.jetbrains.com/blog/2019/05/30/jetbrains-supports-the-apache-software-foundation/) 
+
+### How do I get a apache.org email account to get the IDEA License?
+
+The Apache Software Foundation is an organization, and not a free web host. An ASF account is earned by making sustained 
+and welcome contributions to a project. For more, see:
+
+- [http://apache.org/foundation/faq.html#joining](http://apache.org/foundation/faq.html#joining)
+- [http://apache.org/foundation/how-it-works.html#meritocracy](http://apache.org/foundation/how-it-works.html#meritocracy)
+- [http://struts.apache.org/helping.html](http://struts.apache.org/helping.html)
+
+The reason JetBrains (among others) give committers licenses is because we have earned them by helping to create open 
+source products, many of which JetBrains uses internally.
diff --git a/source/contributors/one-time-steps.md b/source/contributors/one-time-steps.md
index 4b98cc2..efb55b1 100644
--- a/source/contributors/one-time-steps.md
+++ b/source/contributors/one-time-steps.md
@@ -16,7 +16,7 @@ parent:
 
 ### Create and install a SSH key
 
-| See [OpenSSH Public Key Authentication](http://sial.org/howto/openssh/publickey-auth/)
+> See [OpenSSH Public Key Authentication](http://sial.org/howto/openssh/publickey-auth/)
 
 If you get hung up during release:perform because Maven can't verify the authenticity of a host, then there could be 
 one of two  different problems. The first problem, which is an easy fix, is to go to the command line and use SSH 
diff --git a/source/contributors/precise-error-reporting.md b/source/contributors/precise-error-reporting.md
new file mode 100644
index 0000000..f505cc1
--- /dev/null
+++ b/source/contributors/precise-error-reporting.md
@@ -0,0 +1,31 @@
+---
+layout: default
+title: Precise Error Reporting
+parent:
+  title: Contributors Guide
+  url: index.html
+---
+
+# Precise Error Reporting
+{:.no_toc}
+
+* Will be replaced with the ToC, excluding a header
+{:toc}
+
+With the multiple levels of configuration, constant overrides, and bean selection, it can be confusing as to how 
+the framework is configured and how it got there. To assist debugging and provide the ability to continue to provide 
+more line-precise error reporting, the configuration loader remembers the location of not only XML elements, 
+but also Java Properties file properties.
+
+How it works is instead of storing configuration properties in a plain `java.util.Properties` object, we have a special 
+`LocatableProperties` class. This class leverages the location classes to store location information for the whole 
+properties file but also individual properties.  We use this to gather configuration properties during configuration loading. 
+This will allow us to display at any given point the location of each property setting. This capability should be very 
+useful when trying to determine what XML or Properties file overwrote what and when.
+
+Interestingly, in addition to remembering the URI and line number of Properties properties, the parser we "borrowed" 
+from Commons Configuration even gathers preceding comments, which are also stored in the Location object. This means 
+we can leverage the Properties comment-based documentation that we have in the o.a.s.default.properties file
+or the user's struts.properties file to further provide useful information in error reports.
+
+There are some very interesting possibilities here to increase the transparency of the framework in error and debugging conditions.