This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch add-contributing-md in repository https://gitbox.apache.org/repos/asf/struts.git
commit ae440294ff9615884d7beafd3811a9da4cba54bb Author: Lukasz Lenart <[email protected]> AuthorDate: Thu Jun 25 21:35:32 2026 +0200 Add CONTRIBUTING.md for new contributors --- CONTRIBUTING.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..2f01474b2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,118 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +# Contributing to Apache Struts + +Thanks for your interest in contributing! Apache Struts is maintained by a +community of volunteers under the [Apache Software Foundation](https://www.apache.org/). +This guide walks a first-time contributor from a fresh clone to a merged pull +request. You do not need to be a committer to contribute — anyone can open a PR. + +## Getting help + +- **Mailing lists:** Subscribe and ask on the developer or user list — see + <https://struts.apache.org/mail.html>. The developer list is the best place + to discuss a change before you start larger work. +- **Issue tracker:** [JIRA WW project](https://issues.apache.org/jira/projects/WW). +- **Homepage & docs:** <https://struts.apache.org/>. + +If you are unsure whether a change is wanted, ask on the developer list or +comment on the relevant JIRA issue first. + +## Project overview + +Apache Struts is a mature MVC web framework for Java (originally WebWork 2). It +uses OGNL for value-stack expressions and FreeMarker for UI tag templates. The +repository is a multi-module Maven build: + +| Module | Responsibility | +|------------|-------------------------------------------------------------| +| `core` | `struts2-core` — the main framework | +| `plugins` | Plugin modules (json, rest, spring, tiles, velocity, …) | +| `apps` | Sample applications (showcase, rest-showcase) | +| `assembly` | Distribution packaging | +| `bom` | Bill of Materials for dependency management | +| `parent` | Parent POM with shared configuration | +| `jakarta` | Jakarta EE compatibility modules | + +The request lifecycle is `Dispatcher` → `ActionProxy` → `ActionInvocation` → +interceptor stack → `Action` → `Result`. + +## Prerequisites & building + +- **JDK 17** and **Maven**. +- Run the tests (skipping assembly for speed): + + ```bash + mvn test -DskipAssembly + ``` + +- Run a single test in a specific module: + + ```bash + mvn test -DskipAssembly -pl core -Dtest=MyClassTest#testMethodName + ``` + +- Build against the Jakarta EE 11 / Spring 7 profile: + + ```bash + mvn clean install -Pjakartaee11 + ``` + +Tests use JUnit 5 with AssertJ assertions and Mockito for mocking. + +## Finding something to work on + +Browse the [JIRA WW project](https://issues.apache.org/jira/projects/WW) for +open issues. Comment on an issue to let others know you are working on it. If +no ticket exists for your change, **file one first** — every commit and pull +request must reference a `WW-XXXX` ticket ID. + +## Development workflow + +1. Fork the repository and clone your fork. +2. Create a branch off `main` named after the ticket, e.g. `WW-1234-short-description`. +3. Implement your change **with tests**. Keep commits focused. +4. Prefix every commit message with the ticket ID: `WW-1234 Describe the change`. +5. Run `mvn test -DskipAssembly` and make sure it passes before opening a PR. + +## Submitting a pull request + +- **Title format:** `WW-XXXX Description` (the JIRA ticket ID is required). +- **Link the ticket** in the description: + `Fixes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`. +- Continuous integration must pass, and reviewers expect code changes to come + with tests. + +## Reporting security issues + +**Do not** open a public GitHub issue, JIRA issue, pull request, or +mailing-list thread for a suspected vulnerability. Report it privately to +**[email protected]**. See [`SECURITY.md`](SECURITY.md) for the full +process. This includes OGNL injection, parameter-filtering bypasses, file +upload exploits, authentication bypass, RCE, SSRF, path traversal, +deserialization, and XSS in framework components. + +## Licensing & Code of Conduct + +- Apache Struts is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). +- Every new source file must include the standard ASF license header (see any + existing source file or this file's header for the exact text). +- By submitting a pull request you agree to license your contribution under the + Apache License 2.0. The ASF does not require a separate signed CLA for typical + contributions. +- All participation is governed by the + [ASF Code of Conduct](https://www.apache.org/foundation/policies/conduct.html).
