Hi all, Following a discussion on Slack, here is a patch that documents in the README how to contribute changes to projects.apache.org. It covers:
- the GitHub repo being a read-only mirror, so changes go through SVN; - not including the generated data under site/json/, which the projects_role cron commits daily; - how to make a patch (svn diff, or git diff --no-prefix from a clone of the Git mirror) and where to send it (here, or a COMDEV JIRA issue); - commit-then-review for committers, and noting AI-assisted changes with a Generated-by: line. Corrections welcome, especially if I've got the commit/review expectations wrong. Apply with: svn patch readme.patch Generated-by: Claude Opus 5 Jarek --- patch --- Index: README.md =================================================================== --- README.md (revision 1939852) +++ README.md (working copy) @@ -8,6 +8,60 @@ Please do not use Pull Requests. +## Contributing changes + +The GitHub repository (apache/comdev-projects) is a read-only mirror of +the SVN trunk above. Nobody can push to it or merge Pull Requests there, +so changes have to go through SVN. + +### Do not include generated data + +Most files under site/json/ are generated by the scripts in +scripts/cronjobs/ and committed to SVN daily (around 2 AM UTC) by the +projects_role account. Change the script that generates a file, not +the file itself: a hand-edited copy will conflict with, or be +overwritten by, the next scheduled update. + +### Submitting a patch for review + +1. Check out trunk (or update an existing checkout): + + svn checkout https://svn.apache.org/repos/asf/comdev/projects.apache.org/trunk projects.apache.org + cd projects.apache.org + +2. Make and test your change (see "Running locally" below). + +3. Create the patch from the top of the checkout: + + svn diff > my-change.patch + + If you work in a clone of the Git mirror instead, this creates a + patch that "svn patch" can apply, without the generated data: + + git diff --no-prefix origin/trunk...HEAD -- . ':!site/json' > my-change.patch + +4. Send it for review, either: + - to [email protected], with [PATCH] in the subject and the + patch inline in a plain-text email (attachments may be stripped), or + - attached to an issue in https://issues.apache.org/jira/projects/COMDEV + with the component: Projects Tool + +Reviewers apply it with "svn patch my-change.patch". + +### Committing directly + +Committers with write access to comdev may commit their own changes +with "svn commit". The project works commit-then-review: every commit +is sent to [email protected], where it can be reviewed. +For larger or user-visible changes, consider sending a patch to [email protected] first. + +If generative AI tools helped write a change, say so in the commit +message or patch email, for example with a "Generated-by:" line, as +described in https://www.apache.org/legal/generative-tooling.html + +## Running locally + Run a local version of the site with: `cd site && python3 -m http.server 8000` --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
