From 309a0dcb2ff8682a2d2c48113619564ea1aea8c6 Mon Sep 17 00:00:00 2001 From: Justin Mclean Date: Fri, 16 Oct 2026 20:36:20 +1100 Subject: [PATCH 1/3] Fix list markers and indents in pages Turns MD004, MD005, MD007 and MD030 back on and fixes the pages that broke them. Pages render the same apart from the GFMReader extensions in asf-pelican-plugins.md, which now nest under GFMReader. --- .markdownlint-cli2.yaml | 4 - content/blog/2023 Infra Survey Results.md | 136 +++++++-------- content/blog/README.md | 50 +++--- content/blog/add_wisdom.md | 18 +- content/blog/newsletter_01_25.md | 4 +- content/blog/newsletter_02_24.md | 18 +- content/blog/newsletter_03_24.md | 14 +- content/blog/newsletter_03_25.md | 6 +- content/blog/newsletter_03_26.md | 4 +- content/blog/newsletter_04_25.md | 32 ++-- content/blog/newsletter_04_26.md | 10 +- content/blog/newsletter_05_24.md | 6 +- content/blog/newsletter_05_25.md | 20 +-- content/blog/newsletter_05_26.md | 28 +-- content/blog/newsletter_06_24.md | 48 ++--- content/blog/newsletter_06_25.md | 10 +- content/blog/newsletter_06_26.md | 24 +-- content/blog/newsletter_07_24.md | 12 +- content/blog/newsletter_07_25.md | 4 +- content/blog/newsletter_08_25.md | 10 +- content/blog/newsletter_09_25.md | 8 +- content/blog/newsletter_10_25.md | 10 +- content/blog/newsletter_11_24.md | 8 +- content/blog/responding_to_2024_survey.md | 72 ++++---- content/blog/the_joy_of_feedback.md | 8 +- content/blog/trivy_security_incident.md | 10 +- content/pages/account-mgmt.md | 20 +-- content/pages/app-upgrade-policy.md | 12 +- content/pages/apple-dev-program.md | 8 +- content/pages/asf-pelican-data.md | 6 +- content/pages/asf-pelican-gettingstarted.md | 4 +- content/pages/asf-pelican-local.md | 6 +- content/pages/asf-pelican-plugins.md | 20 +-- content/pages/asf-pelican.md | 10 +- content/pages/asf-yaml.md | 8 +- content/pages/asfbot.md | 26 +-- content/pages/asfquart.md | 10 +- content/pages/atr.md | 4 +- content/pages/backup-policy.md | 18 +- content/pages/bug-writing-guide.md | 24 +-- content/pages/build-supported-services.md | 42 ++--- content/pages/code-signing-access.md | 14 +- content/pages/committer-outreach.md | 8 +- content/pages/committers.md | 38 ++-- content/pages/contact.md | 8 +- content/pages/content-moderation.md | 4 +- content/pages/contrib-email-tips.md | 46 ++--- content/pages/contributors.md | 26 +-- content/pages/crypto.md | 26 +-- content/pages/csp.md | 6 +- content/pages/cwiki.md | 38 ++-- content/pages/dependabot.md | 6 +- content/pages/digicert-access.md | 8 +- content/pages/email_lists.md | 44 ++--- content/pages/gfm.md | 10 +- content/pages/git-primer.md | 52 +++--- content/pages/git.md | 6 +- content/pages/github-actions-policy.md | 8 +- content/pages/github-actions-secrets.md | 14 +- content/pages/github-pages.md | 6 +- content/pages/github-roles.md | 16 +- content/pages/glossary.md | 14 +- content/pages/hosting-external-agent.md | 26 +-- content/pages/how-to-mirror.md | 40 ++--- content/pages/infra-contact.md | 14 +- content/pages/infra-incubator.md | 6 +- content/pages/infra-mail.md | 14 +- content/pages/infra-reports.md | 14 +- content/pages/infra-volunteer.md | 14 +- .../pages/jira-account-retention-policy.md | 4 +- content/pages/jira-for-infra.md | 14 +- content/pages/jira-guidelines.md | 10 +- content/pages/key-transition.md | 12 +- content/pages/licensing-howto.md | 36 ++-- content/pages/mailing-list-moderation.md | 50 +++--- content/pages/mfa-reset.md | 6 +- content/pages/mfa.md | 4 +- content/pages/new-committers-guide.md | 66 +++---- content/pages/nightlies.md | 14 +- content/pages/open-access-svn.md | 40 ++--- content/pages/openpgp.md | 100 +++++------ content/pages/os-upgrade-policy.md | 8 +- content/pages/pelican-buildbot.md | 12 +- content/pages/phishing.md | 6 +- content/pages/project-repo-policy.md | 30 ++-- content/pages/project-site.md | 62 +++---- content/pages/publishing-maven-artifacts.md | 28 +-- content/pages/qbot.md | 84 ++++----- content/pages/release-distribution.md | 78 ++++----- content/pages/release-download-pages.md | 46 ++--- content/pages/release-integrity-primer.md | 4 +- content/pages/release-publishing.md | 44 ++--- content/pages/release-signing.md | 124 ++++++------- content/pages/repository-faq.md | 4 +- content/pages/request-bug-tracker.md | 12 +- content/pages/responsetime.md | 46 ++--- content/pages/roundtable.md | 14 +- content/pages/sensitive_info.md | 8 +- content/pages/services.md | 164 +++++++++--------- content/pages/slack.md | 18 +- content/pages/stats.md | 12 +- content/pages/svn-basics.md | 8 +- content/pages/svngit2jira.md | 12 +- content/pages/user-ssh.md | 20 +-- content/pages/version-control.md | 42 ++--- content/pages/vm-for-project.md | 38 ++-- content/pages/vm-management.md | 40 ++--- content/pages/vm-policy.md | 4 +- 108 files changed, 1319 insertions(+), 1323 deletions(-) diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 8c0b508f4..d7e22d00d 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -15,9 +15,6 @@ config: # are cleaned up. MD001: false MD003: false - MD004: false - MD005: false - MD007: false MD010: false MD014: false MD018: false @@ -25,7 +22,6 @@ config: MD025: false MD026: false MD029: false - MD030: false MD034: false MD036: false MD038: false diff --git a/content/blog/2023 Infra Survey Results.md b/content/blog/2023 Infra Survey Results.md index a7e042e47..22365f07f 100644 --- a/content/blog/2023 Infra Survey Results.md +++ b/content/blog/2023 Infra Survey Results.md @@ -15,24 +15,24 @@ We're grateful to those who took the time to fill out the survey. Without feedba Some reasons for not having attended include: - - Time constraints (most frequent response) - - Was not aware it existed - - Do not need it / no pressing issues - - Timezone issues (the roundtables frequently happen at a time which is more convenient to people in Europe and North American than in Asia) +- Time constraints (most frequent response) +- Was not aware it existed +- Do not need it / no pressing issues +- Timezone issues (the roundtables frequently happen at a time which is more convenient to people in Europe and North American than in Asia) 88.9% say the roundtables ‘provide value’. Topics respondents would like roundtables to address: - - Things Infra is working on that might be useful to PMCs - - Vulnerability scanning - - Automation of - - voting - - policy compliance verification - - releases - - Ways to make it easier for contributors to projects to contribute to Infra coding tasks - - Periodic hackathons Infra hackathons open to all contributors - - Series of FAQs / tutorials on common tasks at the ASF +- Things Infra is working on that might be useful to PMCs +- Vulnerability scanning +- Automation of + - voting + - policy compliance verification + - releases +- Ways to make it easier for contributors to projects to contribute to Infra coding tasks +- Periodic hackathons Infra hackathons open to all contributors +- Series of FAQs / tutorials on common tasks at the ASF ### Communication @@ -40,14 +40,14 @@ Topics respondents would like roundtables to address: Further communications improvement suggestions included: - - Periodic newsletter (implemented!) - - Email announcements of important matters to all members - - Better connection of each Infra service with its documentation - - News box on the landing page at `infra.a.o` needs to be updated more frequently - - Questions to `users@infra.a.o` seem to go unanswered - - Be more consistent in showing latest and earlier versions of info on the wiki pages - - Public archive containing summaries of all main points in all roundtables - - Periodic publication of the basic stuff, such as 'Where is self-serve?' +- Periodic newsletter (implemented!) +- Email announcements of important matters to all members +- Better connection of each Infra service with its documentation +- News box on the landing page at `infra.a.o` needs to be updated more frequently +- Questions to `users@infra.a.o` seem to go unanswered +- Be more consistent in showing latest and earlier versions of info on the wiki pages +- Public archive containing summaries of all main points in all roundtables +- Periodic publication of the basic stuff, such as 'Where is self-serve?' ### Technical services @@ -55,65 +55,65 @@ Further communications improvement suggestions included: Service improvement suggestions: - - Proactively improve the security posture of all ASF projects - - Automating releases (this is coming!) and dependency upgrades for CVE mitigation - - Free BSD runners and CI builder on GitHub - - More docs and examples for VM setup via puppet - - Password management solution - - More powerful GitHub Action runners for all platforms - - Video call service +- Proactively improve the security posture of all ASF projects +- Automating releases (this is coming!) and dependency upgrades for CVE mitigation +- Free BSD runners and CI builder on GitHub +- More docs and examples for VM setup via puppet +- Password management solution +- More powerful GitHub Action runners for all platforms +- Video call service We asked which existing services need improvement. These areas got the most votes: - - CI/CD (Jenkins, BuildBot, GitHub Actions – 62% - - Issue Tracking (Jira, GitHubIssues, Bugzilla) – 31% - - Documentation / Wiki pages – 31% - - Source control (GitHub/GitBox, SVN) – 19% - - Messaging (Slack, mailing lists) – 19% +- CI/CD (Jenkins, BuildBot, GitHub Actions – 62% +- Issue Tracking (Jira, GitHubIssues, Bugzilla) – 31% +- Documentation / Wiki pages – 31% +- Source control (GitHub/GitBox, SVN) – 19% +- Messaging (Slack, mailing lists) – 19% Comments: - - Archived blog content is greatly bit rotted with no way to fix; no good modern blogging options - - ASF project websites vary widely in visual appeal and functionality. How to make it easier to quickly set up ‘modern looking’ websites? - - Issue tracking – automated scripts to migrate existing issues from Jira to GitHub Issues. - - Fix tool sprawl – self-serve, whimsy, reporter, cveprocess... - - Jenkins seems outdated. Would prefer something like Concourse. - - Research an official Stack Overflow integration as an alternative to users’ lists? - - In CI/CD, we don’t really have any CD. Where can we deploy test apps? - - Docker Images. - - More control over Docker Hub repos. - - Builds are sometimes flaky because of disk-full error, broken hardware, missing build tools... - - Builds are very slow for projects with a large number of modules and different workflows for different test suites. Such projects need more dedicated resources. - - It’s easy for projects to configure build pipelines that don’t work well. - - I shouldn’t have to create a filter to understand the context of an email from the ASF. - - Struggling to find good documentation on Buildbot hosts, in particular for setting up a Windows build. - - In a multilanguage project, Kotlin is not counted. - - Mailing list noise from GitHub/GitBox. Drop messages from some bots. - - Need a simple build caching solution for Jenkins so we can cache Maven repositories between builds - - Need a good template for the static part of project websites. (Working on it!) - - There is no documentation on cleanup after a build and main + subpath deployment of a website, nor an example to start with. - - Long build queues on ASF Jenkins; problems with GHA builds - - Jenkins builds should be containerized and isolated from one another, so one build does not bring down a node for everybody else. Need guaranteed minimum performance for performance-sensitive build tests. - - Improve the messaging of Jira to the mailing lists. +- Archived blog content is greatly bit rotted with no way to fix; no good modern blogging options +- ASF project websites vary widely in visual appeal and functionality. How to make it easier to quickly set up ‘modern looking’ websites? +- Issue tracking – automated scripts to migrate existing issues from Jira to GitHub Issues. +- Fix tool sprawl – self-serve, whimsy, reporter, cveprocess... +- Jenkins seems outdated. Would prefer something like Concourse. +- Research an official Stack Overflow integration as an alternative to users’ lists? +- In CI/CD, we don’t really have any CD. Where can we deploy test apps? +- Docker Images. +- More control over Docker Hub repos. +- Builds are sometimes flaky because of disk-full error, broken hardware, missing build tools... +- Builds are very slow for projects with a large number of modules and different workflows for different test suites. Such projects need more dedicated resources. +- It’s easy for projects to configure build pipelines that don’t work well. +- I shouldn’t have to create a filter to understand the context of an email from the ASF. +- Struggling to find good documentation on Buildbot hosts, in particular for setting up a Windows build. +- In a multilanguage project, Kotlin is not counted. +- Mailing list noise from GitHub/GitBox. Drop messages from some bots. +- Need a simple build caching solution for Jenkins so we can cache Maven repositories between builds +- Need a good template for the static part of project websites. (Working on it!) +- There is no documentation on cleanup after a build and main + subpath deployment of a website, nor an example to start with. +- Long build queues on ASF Jenkins; problems with GHA builds +- Jenkins builds should be containerized and isolated from one another, so one build does not bring down a node for everybody else. Need guaranteed minimum performance for performance-sensitive build tests. +- Improve the messaging of Jira to the mailing lists. ### New Year’s resolutions for projects: - - Hope to make more frequent releases (multiple mentions). - - Get it fully, reproducibly built with OID integration to release it via Trusted Publishing to PyPI. - - Reduce ‘onboarding barriers’ and bridging projects for more synergy. - - Add documentation tutorials. - - Attracting more people to work on the documentation. +- Hope to make more frequent releases (multiple mentions). +- Get it fully, reproducibly built with OID integration to release it via Trusted Publishing to PyPI. +- Reduce ‘onboarding barriers’ and bridging projects for more synergy. +- Add documentation tutorials. +- Attracting more people to work on the documentation. ### New Year’s hopes to get from Infra, the ASF, from your project - - Easy to use and secure package and releasing platform (Working on it!) - - More reliability - - An arrangement with medium or substack - - FreeBSD/BSD - - More stability for Ubuntu Jenkins nodes - - automated voting tool (Working on it!) - - CI stabiity - - More powerful GitHub Runners for all platforms +- Easy to use and secure package and releasing platform (Working on it!) +- More reliability +- An arrangement with medium or substack +- FreeBSD/BSD +- More stability for Ubuntu Jenkins nodes +- automated voting tool (Working on it!) +- CI stabiity +- More powerful GitHub Runners for all platforms ### Feedback for the Infra team: diff --git a/content/blog/README.md b/content/blog/README.md index 12243074a..87f078793 100644 --- a/content/blog/README.md +++ b/content/blog/README.md @@ -1,7 +1,7 @@ ## The Infra Blog - - [index.md](index.md) is the wheelhouse for the blog. There you define the general title and which template the blog is using. - - The blog's template defines the look and feel of the blog page, and also calls the blog articles for display. +- [index.md](index.md) is the wheelhouse for the blog. There you define the general title and which template the blog is using. +- The blog's template defines the look and feel of the blog page, and also calls the blog articles for display. ### Blog entry metadata @@ -9,30 +9,30 @@ Metadata includes the title of the entry and the date it was published. Pelican Required metadata: For each blog entry, make sure you provide the following metadata at the top of the file: - - layout: post - - title: the article's title - - date: the date the post first appeared (yyyy-mm-dd) - - permalink: a short phrase identifying the post - - category: content category. Only provide ONE for each blog post. Current options are `event`, `general`, `infra`, `policy`, `projects`, `security`, `service`, `tools`. _note: filtering is not enabled yet._ +- layout: post +- title: the article's title +- date: the date the post first appeared (yyyy-mm-dd) +- permalink: a short phrase identifying the post +- category: content category. Only provide ONE for each blog post. Current options are `event`, `general`, `infra`, `policy`, `projects`, `security`, `service`, `tools`. _note: filtering is not enabled yet._ These metadata fields are available, but are currently optional for the Infra blog: - - author: content author, when there is just one - - authors: separate the names of multiple content authors with commas - - keywords: content keywords, separated by commas (HTML content only) - - modified: the most recent date of changes to the post (yyyy-mm-dd) - - slug: identifier used in URLs and translations - - status: options are `draft`, `hidden`, or `published` - - summary: brief description for use on index pages - - tags: content tags, separated by commas - - url: URL to use for this article +- author: content author, when there is just one +- authors: separate the names of multiple content authors with commas +- keywords: content keywords, separated by commas (HTML content only) +- modified: the most recent date of changes to the post (yyyy-mm-dd) +- slug: identifier used in URLs and translations +- status: options are `draft`, `hidden`, or `published` +- summary: brief description for use on index pages +- tags: content tags, separated by commas +- url: URL to use for this article Pelican supports these tags, which the Infra blog does not use: - - lang: content language ID - - save_as: save content to this relative file path - - template: template to use to generate content - - translation (true or false) +- lang: content language ID +- save_as: save content to this relative file path +- template: template to use to generate content +- translation (true or false) The first line of the file should have this metadata, at a minimum: @@ -56,12 +56,12 @@ category CATEGORY To create an entry, create an .md file in this folder. The file's name should probably be like the permalink for the entry. - - give the file a meaningful title that does not duplicate one we have used already. - - Starting at the first line of the file, add metadata for the entry, as described above. +- give the file a meaningful title that does not duplicate one we have used already. +- Starting at the first line of the file, add metadata for the entry, as described above. - - Write your entry using Markdown. - - If you do not want to publish the blog post as soon as you commit it to the repository, set the metadata `status: draft`. When you are ready to publish the post, change the status to `published` or remove the `status` metadata altogether. Then commit the file. - - You can edit the entry at any time. Updating an older entry does not move it to the top of the blog's display. +- Write your entry using Markdown. +- If you do not want to publish the blog post as soon as you commit it to the repository, set the metadata `status: draft`. When you are ready to publish the post, change the status to `published` or remove the `status` metadata altogether. Then commit the file. +- You can edit the entry at any time. Updating an older entry does not move it to the top of the blog's display. ### Making use of the search feature diff --git a/content/blog/add_wisdom.md b/content/blog/add_wisdom.md index 2b2d4c455..08d881d12 100644 --- a/content/blog/add_wisdom.md +++ b/content/blog/add_wisdom.md @@ -19,8 +19,8 @@ Infra holds regular roundtable discussions on important topics in the World of I The roundtables usually take place on the **first Wednesday of each month**, on the `#roundtable` channel in the `the-ASF` workspace on Slack. They are available to anyone who can access the ASF workspace on Slack: basically, committers and Members. - - Here are details about the Roundtables, including information on joining the `#roundtable` channel. - - We don't record the sessions, but we do take copious notes. +- Here are details about the Roundtables, including information on joining the `#roundtable` channel. +- We don't record the sessions, but we do take copious notes. **Build better builds** @@ -30,13 +30,13 @@ A group meets regularly (usually the second Thursday of the month) in the `#buil Infra is starting to develop the **Artifacts Distribution Platform** (ADP). The idea is to consolidate `dist.apache.org`, `downloads.apache.org`, `rsync.apache.org` and `archive.apache.org` into one service that will free up resources and: - - simplify backups of release artifacts - - remove the need to "police" projects about their release pages by no longer requiring them to manually archive older releases - - ensure that all new releases follow our release policies by only allowing policy-compliant artifacts to be released - - make it easier for product users to verify that what they are about to download is a certified ASF artifact +- simplify backups of release artifacts +- remove the need to "police" projects about their release pages by no longer requiring them to manually archive older releases +- ensure that all new releases follow our release policies by only allowing policy-compliant artifacts to be released +- make it easier for product users to verify that what they are about to download is a certified ASF artifact We are assembling lists of necessary features, 'good to have' features, and ambitious pipe dreams, and value input from all across the The ASF's communities. - - Join the `artifacts@infra.apache.org` mailing list. - - Ask to be invited to the `artifact-platform-dev` channel in the `the-ASF` workspace on Slack. - - Review the current collection of ideas and issues related to the ADP. Add your thoughts/concerns/insights in the editable pages linked to from that main page. (Note: we have already blue-skied a very complex application. If you suggest another component, we may invite you to help develop it.) +- Join the `artifacts@infra.apache.org` mailing list. +- Ask to be invited to the `artifact-platform-dev` channel in the `the-ASF` workspace on Slack. +- Review the current collection of ideas and issues related to the ADP. Add your thoughts/concerns/insights in the editable pages linked to from that main page. (Note: we have already blue-skied a very complex application. If you suggest another component, we may invite you to help develop it.) diff --git a/content/blog/newsletter_01_25.md b/content/blog/newsletter_01_25.md index 1585db452..7b2b92288 100644 --- a/content/blog/newsletter_01_25.md +++ b/content/blog/newsletter_01_25.md @@ -20,8 +20,8 @@ See this page Staring March 1, 2025, the ASF will be enforcing a **Content Security Policy** (CSP) for all project websites. - - External trackers from 3rd party providers are NO LONGER allowed - - External resources from providers with which we do not have a Data Processing Agreement (DPA) are NO LONGER allowed +- External trackers from 3rd party providers are NO LONGER allowed +- External resources from providers with which we do not have a Data Processing Agreement (DPA) are NO LONGER allowed This policy will bring project websites into alignment with The ASF's security and privacy parameters. diff --git a/content/blog/newsletter_02_24.md b/content/blog/newsletter_02_24.md index aef5a9b44..bbabf5e0a 100644 --- a/content/blog/newsletter_02_24.md +++ b/content/blog/newsletter_02_24.md @@ -21,11 +21,11 @@ The survey summary is on our github.com/apache/infrastructure-asfyaml/blob/main/README.md. diff --git a/content/blog/newsletter_03_24.md b/content/blog/newsletter_03_24.md index d2dfc0225..6c7870f04 100644 --- a/content/blog/newsletter_03_24.md +++ b/content/blog/newsletter_03_24.md @@ -9,11 +9,11 @@ Welcome to **Inside Infra** for March, 2024. Due to misconfigurations in their builds, some projects have been using unsupportable numbers of GitHub Actions. As part of fixing this situation, Infra has added a 'resource use' section to the policy on GitHub Actions. This section of the policy will come into effect on **April 20, 2024**: - - All workflows MUST have a job concurrency level less than or equal to 20. This means a workflow cannot have more than 20 jobs running at the same time across all matrices. - - All workflows SHOULD have a job concurrency level less than or equal to 15. Just because 20 is the max, doesn't mean you should strive for 20. - - The average number of minutes a project uses per calendar week MUST NOT exceed the equivalent of 25 full-time runners (250,000 minutes, or 4,200 hours). - - The average number of minutes a project uses in any consecutive five-day period MUST NOT exceed the equivalent of 30 full-time runners (216,000 minutes, or 3,600 hours). - - Projects whose builds consistently cross the maximum use limits will lose their access to GitHub Actions until they fix their build configurations. +- All workflows MUST have a job concurrency level less than or equal to 20. This means a workflow cannot have more than 20 jobs running at the same time across all matrices. +- All workflows SHOULD have a job concurrency level less than or equal to 15. Just because 20 is the max, doesn't mean you should strive for 20. +- The average number of minutes a project uses per calendar week MUST NOT exceed the equivalent of 25 full-time runners (250,000 minutes, or 4,200 hours). +- The average number of minutes a project uses in any consecutive five-day period MUST NOT exceed the equivalent of 30 full-time runners (216,000 minutes, or 3,600 hours). +- Projects whose builds consistently cross the maximum use limits will lose their access to GitHub Actions until they fix their build configurations. The full policy is at https://infra.apache.org/github-actions-policy.html. @@ -21,8 +21,8 @@ The full policy is at https://cwiki.apache.org/confluence/display/INFRA/Infra+Roundtable+2024-03-06%2C+17%3A00+UTC, and is available to ASF Members and Committers. diff --git a/content/blog/newsletter_03_25.md b/content/blog/newsletter_03_25.md index ef8485af3..0be926b94 100644 --- a/content/blog/newsletter_03_25.md +++ b/content/blog/newsletter_03_25.md @@ -16,9 +16,9 @@ The team is debugging the complex flow of commits and action triggers to our pub Remaining tasks include - - dependabot update bundling - - watcher service re-scanning - - polishing up workflow triggers +- dependabot update bundling +- watcher service re-scanning +- polishing up workflow triggers If you are interested in following this work more closely, or contributing to it, please join our email list (`ghactions@infra.apache.org`) and/or the **#asf-ghactions** channel in the the-apache space on Slack. diff --git a/content/blog/newsletter_03_26.md b/content/blog/newsletter_03_26.md index 1513404e2..0c3dd780e 100644 --- a/content/blog/newsletter_03_26.md +++ b/content/blog/newsletter_03_26.md @@ -20,8 +20,8 @@ The next Roundtable will be **April 1, 1700 UTC** on the roundtable channel in t Looking ahead: - - The May Roundtable will be **May 6, 1700 UTC** with the topic: **What is the impact on our infrastructure of AI coding?** - - On **June 3, 1700 UTC**, Piotr P. Karwasz presents at the roundtable on **release automation** +- The May Roundtable will be **May 6, 1700 UTC** with the topic: **What is the impact on our infrastructure of AI coding?** +- On **June 3, 1700 UTC**, Piotr P. Karwasz presents at the roundtable on **release automation** Information on roundtables, and how to take part in one, is at infra.apache.org/roundtable.html diff --git a/content/blog/newsletter_04_25.md b/content/blog/newsletter_04_25.md index 06cce2f9e..997182210 100644 --- a/content/blog/newsletter_04_25.md +++ b/content/blog/newsletter_04_25.md @@ -8,13 +8,13 @@ permalink: newsletter0425 layout: post The April roundtable was an 'open mic' session, to which people were encouraged to bring their fascinating or festering issues. Topics included: - - the dynamics in choirs and voluntary organizations in general and how they map to the dynamics in ASF Member interrelations - - where project VMs are hosted - - how to find the APIs of services Infra provides - - what a pipservice is, and whether a pipservice sandbox would be useful to project committers - - the allowlist for custom GitHub Actions - - whether custom GHAs need to include Apache licenses (short answer is 'no') - - how to find out if the ASF has blocked your IP address, and why (see below) +- the dynamics in choirs and voluntary organizations in general and how they map to the dynamics in ASF Member interrelations +- where project VMs are hosted +- how to find the APIs of services Infra provides +- what a pipservice is, and whether a pipservice sandbox would be useful to project committers +- the allowlist for custom GitHub Actions +- whether custom GHAs need to include Apache licenses (short answer is 'no') +- how to find out if the ASF has blocked your IP address, and why (see below) There is **no roundtable in May**. The next roundtable will be **Wednesday, June 4, 2025, 1700 UTC**. The main topic will be a presentation on **JFrog and Artifactory**, a universal binary repository manager that enables teams to store, manage, and organize software packages throughout the development lifecycle. @@ -24,10 +24,10 @@ There is **no roundtable in May**. The next roundtable will be **Wednesday, June Recent enhancements to .asf.yaml make it easier for projects to manage their development environments, including: - - identifying required reviewers for the release - - create a display between when you trigger a deployment and when the deployment process actually starts - - an option to allow deploying from all protected branches - - improvements to the branch and tagging processes +- identifying required reviewers for the release +- create a display between when you trigger a deployment and when the deployment process actually starts +- an option to allow deploying from all protected branches +- improvements to the branch and tagging processes More details are available in this part of the .asf.yaml README file: [https://github.com/apache/infrastructure-asfyaml?tab=readme-ov-file#environments](github.com/apache/infrastructure-asfyaml?tab=readme-ov-file#environments) @@ -37,9 +37,9 @@ At the end of May, 2025, Infra will be removing the deprecated Bulk migration Maven jobs - - Pipeline - - Video: Darin Pope, Cloudbees Advocate, goes through the steps to migrate +- Bulk migration Maven jobs +- Pipeline +- Video: Darin Pope, Cloudbees Advocate, goes through the steps to migrate Infra's Gavin McDonald has checked all project controllers, and sees that very few projects are still using the Maven type job, so this removal should affect almost nobody. If, however, you have concerns or would like help with migrating your project's Maven-type job, Infra is only to happy to help. @@ -53,8 +53,8 @@ We now have 99,115 Jira accounts that have been inactive for more than three yea This volume of accounts puts an unnecessary burden on our system, and Infra will be taking steps to reduce the account count: - - We will **delete** accounts that are more than a year old and have never had any activity. - - We will **disable and anonymize** accounts that have been inactive for the past three years, retaining the record of their activity before that time. +- We will **delete** accounts that are more than a year old and have never had any activity. +- We will **disable and anonymize** accounts that have been inactive for the past three years, retaining the record of their activity before that time. ASF Members and project committers can help lighten the load by making sure to always use a Jira account with your ASF credentials (username, email address as they appear in the ICLA you submitted) whenever creating or commenting on a ticket for the ASF, or related to any of our projects. diff --git a/content/blog/newsletter_04_26.md b/content/blog/newsletter_04_26.md index 2473ca054..708220cc7 100644 --- a/content/blog/newsletter_04_26.md +++ b/content/blog/newsletter_04_26.md @@ -10,9 +10,9 @@ The April 1 Roundtable focused on the migration of the ASF's Confluence Wiki and There are significant technical challenges in the migration: - - We have 1.2 million Confluence pages related to The ASF, its committees, and most of its projects. - - We have a similar number of Jira tickets related to 682 ASF projects. We have to migrate them all, even the tickets related to retired projects, to maintain project development history. - - We have over 150,000 user accounts for Jira and almost 100,000 for Confluence (many ASF-related people have one of each, of course). Many of these are inactive. We have to get our combined number of accounts down to 75,000. +- We have 1.2 million Confluence pages related to The ASF, its committees, and most of its projects. +- We have a similar number of Jira tickets related to 682 ASF projects. We have to migrate them all, even the tickets related to retired projects, to maintain project development history. +- We have over 150,000 user accounts for Jira and almost 100,000 for Confluence (many ASF-related people have one of each, of course). Many of these are inactive. We have to get our combined number of accounts down to 75,000. The migration task needs more projects to volunteer to take part so we can address any issues that come up before we do the migration. Project PMCs can express their interest in a message to `users@infra`, in an Infra Jira ticket, or in the conversation on the `#atlassian-cloud-migration` channel in the `the-asf` Slack space. @@ -34,8 +34,8 @@ Further information is at the section on rulesets in the `.asf.yaml` README file. - - **CoPilot code review** can review code written in any coding language and provide feedback. It reviews your code from multiple angles to identify issues and suggest fixes, which you can apply with a couple of clicks. See the section on Copilot code review in the `.asf.yaml` README file. +- **Rulesets** help you control how people can interact with branches and tags in a repository. See the section on rulesets in the `.asf.yaml` README file. +- **CoPilot code review** can review code written in any coding language and provide feedback. It reviews your code from multiple angles to identify issues and suggest fixes, which you can apply with a couple of clicks. See the section on Copilot code review in the `.asf.yaml` README file. ### Infra at C/C Glasgow diff --git a/content/blog/newsletter_05_24.md b/content/blog/newsletter_05_24.md index 4c95e446b..3aaa511b3 100644 --- a/content/blog/newsletter_05_24.md +++ b/content/blog/newsletter_05_24.md @@ -25,8 +25,8 @@ The June Roundtable will take place **June 5 at 1700UTC**, on the roundtable cha The Infrastructure team will be taking part in all three Community Over Code (CoC) events this year: - - CoC Europe, June 3-5, Bratislava, Slovakia - eu.communityovercode.org. Three Infra team members will be present. - - CoC Asia, July 26-28, Hangzhou, China - asia.communityovercode.org. One Infra team member will be taking part. - - CoC North America, October 7-10, Denver, Colorado USA - communityovercode.org. The full team will be at the conference, and will be presenting a track of four talks. +- CoC Europe, June 3-5, Bratislava, Slovakia - eu.communityovercode.org. Three Infra team members will be present. +- CoC Asia, July 26-28, Hangzhou, China - asia.communityovercode.org. One Infra team member will be taking part. +- CoC North America, October 7-10, Denver, Colorado USA - communityovercode.org. The full team will be at the conference, and will be presenting a track of four talks. More news coming in the June issue! diff --git a/content/blog/newsletter_05_25.md b/content/blog/newsletter_05_25.md index 48ccdf9e1..a4eb50cc1 100644 --- a/content/blog/newsletter_05_25.md +++ b/content/blog/newsletter_05_25.md @@ -14,9 +14,9 @@ Information about how to take part in a roundtable is at Contacting Infra if you are reporting a security issue specific to an ASF project or a project's product. +- `users@infra.apache.org` is for general infrastructure discussions and suggestions, and for questions related to ASF infrastructure and the Infra team that do not rise to the level of a Jira ticket. Only committers and ASF members can subscribe to the list. +- `private@infra.apache.org` is for communications that may involve PII, personnel issues, or other information that should not be widely shared. Only ASF Members can subscribe to the list. +- `root@apache.org` is an unarchived alias that goes to Infra staff only for Infra-related security issues or other private matters that don't fit other lists. See the third entry on Contacting Infra if you are reporting a security issue specific to an ASF project or a project's product. In the past there was the `infrastructure@apache.org` mailing list. This address is no longer in use. @@ -26,9 +26,9 @@ At the end of May, 2025, Infra will be removing the deprecated Cloudbees Maven I For further information, see: - - help-bulk-migration-maven-jobs - - plugins.jenkins.io/pipeline-maven/ - - a YouTube video: Darin Pope, Cloudbees Advocate, goes through the steps to migrate +- help-bulk-migration-maven-jobs +- plugins.jenkins.io/pipeline-maven/ +- a YouTube video: Darin Pope, Cloudbees Advocate, goes through the steps to migrate Gavin McDonald has checked all project controllers, and sees that very few projects are still using the Maven type job, so this removal should affect almost nobody. If, however, you have concerns or would like help with migrating your project's Maven-type job, Infra is only to happy to help. @@ -56,10 +56,10 @@ You can add and remove external collaborators to your GitHub repository using .a If you invited a collaborator and they missed the invitation (they're only valid for seven days), simply - - remove them from the collaborator section in your .asf.yaml - - commit and push the change - - re-add them to the collaborator section - - commit and push that change +- remove them from the collaborator section in your .asf.yaml +- commit and push the change +- re-add them to the collaborator section +- commit and push that change They will receive a new invitation. diff --git a/content/blog/newsletter_05_26.md b/content/blog/newsletter_05_26.md index 4749e3c76..463775883 100644 --- a/content/blog/newsletter_05_26.md +++ b/content/blog/newsletter_05_26.md @@ -16,17 +16,17 @@ Once the tool has a suitable name, it will be made generally available to ASF pr Discussion then addressed the challenges and opportunities AI coding presents to the ASF. Some comments: - - Jarek Potiuk: Programming with AI seems to be a huge change in the way we do programming, and this makes a lot of people uneasy. There is an emotional journey toward embracing AI. A huge amount of code now is ai-generated or ai-supported. - - Henri Yandell : AI and Jacquard looms are chapters of the same story, along with moving beyond punch cards and printing presses requiring manual placing of physical letters - - Bob Thomson: none of this is currently profitable, so costs necessarily will increase massively - also no sign of the usual thing with technology where it gets cheaper; so far, rather the opposite. - - Danny Angus: I do think we are behind the curve in ai-adoption for ops. We aren't building up repositories of prompts and steering. We certainly don't have agentic feedback loops +- Jarek Potiuk: Programming with AI seems to be a huge change in the way we do programming, and this makes a lot of people uneasy. There is an emotional journey toward embracing AI. A huge amount of code now is ai-generated or ai-supported. +- Henri Yandell : AI and Jacquard looms are chapters of the same story, along with moving beyond punch cards and printing presses requiring manual placing of physical letters +- Bob Thomson: none of this is currently profitable, so costs necessarily will increase massively - also no sign of the usual thing with technology where it gets cheaper; so far, rather the opposite. +- Danny Angus: I do think we are behind the curve in ai-adoption for ops. We aren't building up repositories of prompts and steering. We certainly don't have agentic feedback loops A summary of the discussion is at Infra Roundtable 2026-05-06. The next two roundtables will be - - June 3, 1700 UTC. Piotr P. Karwasz will present on **release automation**. - - July 1, 1700 UTC. Clay Johnson of Gradle will present on **predictive test analysis**. +- June 3, 1700 UTC. Piotr P. Karwasz will present on **release automation**. +- July 1, 1700 UTC. Clay Johnson of Gradle will present on **predictive test analysis**. Details about joining a roundtable, and what goes on at one, are here: infra.apache.org/roundtable.html. @@ -38,14 +38,14 @@ The soft launch of the new multi-factor authorization system for the ASF started The Infrastructure team will present a full track at Community over Code Glasgow, October 11-14: - - Apache Trusted Releases: Securing the Open Source Supply Chain - - CI Workshop - - Defending the Foundation: Implementing Automated Integrity Validation (AIV) Gates for Apache Projects - - Distributed Denial of Service: Traffic characterization and mitigation - - How To Infra - - Infra Deployment Workshop - - IRL Roundtable - - Where are we going with ASF Infra? +- Apache Trusted Releases: Securing the Open Source Supply Chain +- CI Workshop +- Defending the Foundation: Implementing Automated Integrity Validation (AIV) Gates for Apache Projects +- Distributed Denial of Service: Traffic characterization and mitigation +- How To Infra +- Infra Deployment Workshop +- IRL Roundtable +- Where are we going with ASF Infra? Additionally, Infra will be hosting Games Night, which was very popular at the 2025 convention. diff --git a/content/blog/newsletter_06_24.md b/content/blog/newsletter_06_24.md index d03c1cffd..42d7c3179 100644 --- a/content/blog/newsletter_06_24.md +++ b/content/blog/newsletter_06_24.md @@ -27,30 +27,30 @@ Members of the ASF community have lots of good ideas for services Infra could pr Infra has set up "Infrastructure-ideas" (github.com/apache/infrastructure-ideas), a GitHub repository to host, discuss, and get consensus on people's ideas for ASF infrastructure. For now, we will mainly be making use of the repo's "Discussions" tab. - - Start a new discussion in the category that best matches it: - - Enhancements - - General - - New ideas for services - - Polls - - Q&A - - If you see a suggestion that you agree with, you can upvote it. This helps to demonstrate how broadly the community supports the idea, and that, in turn, could help Infra decide which ideas to devote resources toward implementing. - - If you want to flesh out a suggestion, feel free to add a comment, a question, a challenge, a tweak to it. +- Start a new discussion in the category that best matches it: + - Enhancements + - General + - New ideas for services + - Polls + - Q&A +- If you see a suggestion that you agree with, you can upvote it. This helps to demonstrate how broadly the community supports the idea, and that, in turn, could help Infra decide which ideas to devote resources toward implementing. +- If you want to flesh out a suggestion, feel free to add a comment, a question, a challenge, a tweak to it. We look forward to your ideas! **The new ASF distribution platform** Infra developing the Artifacts Distribution Platform (ADP). The idea is to consolidate dist.apache.org, downloads.apache.org, rsync.apache.org and archive.apache.org into one service that will free up resources and: - - simplify backups of release artifacts - - remove the need to "police" projects about their release pages by no longer requiring them to manually archive older releases - - ensure that all new releases follow our release policies by only allowing policy-compliant artifacts to be released - - make it easier for product users to verify that what they are about to download is a certified ASF artifact +- simplify backups of release artifacts +- remove the need to "police" projects about their release pages by no longer requiring them to manually archive older releases +- ensure that all new releases follow our release policies by only allowing policy-compliant artifacts to be released +- make it easier for product users to verify that what they are about to download is a certified ASF artifact We have assembled lists of necessary features, 'good to have' features, and ambitious pipe dreams, and value input from all across the The ASF's communities, and development is well underway. We expect to bring the distribution platform on-line in stages, with the first stage becoming available late in 2024 or early in 2025. - - Join the `artifacts@infra.apache.org` mailing list. - - Ask to be invited to the `artifact-platform-dev` channel in the `the-ASF` workspace on Slack. - - Review the current collection of ideas and issues related to the ADP. Add your thoughts/concerns/insights in the editable pages linked to from that main page. (Note: we have already blue-skied a very complex application. If you suggest another component, we may invite you to help develop it.) +- Join the `artifacts@infra.apache.org` mailing list. +- Ask to be invited to the `artifact-platform-dev` channel in the `the-ASF` workspace on Slack. +- Review the current collection of ideas and issues related to the ADP. Add your thoughts/concerns/insights in the editable pages linked to from that main page. (Note: we have already blue-skied a very complex application. If you suggest another component, we may invite you to help develop it.) **Note**: the name of the platform may change before it goes live. @@ -58,19 +58,19 @@ We have assembled lists of necessary features, 'good to have' features, and ambi The June, 2024 Roundtable reviewed and discussed tools and resources that every PMC should consider using: - - Virtual machines - the bread and butter of The ASF. Each project can use an Infra-supported virtual machine for free. - - .asf.yaml - Lets project manage their own website development and many other things. . - - self-serve - Provides many tools for Committers, project leaders, and ASF Members. +- Virtual machines - the bread and butter of The ASF. Each project can use an Infra-supported virtual machine for free. +- .asf.yaml - Lets project manage their own website development and many other things. . +- self-serve - Provides many tools for Committers, project leaders, and ASF Members. Confluence and Jira - Wiki and ticketing system from Atlassian. - - Apache STeVe - Voting tool for the ASF and for projects. It is its own top level project. - - Slack - A project channel in the 'the-asf' space can be a communications hub for a project rather than, say, IRC. - - Infra Reports - Dashboard covering resource uptime, public download statistics, use of GitHub Actions, the project website resource checker, and so on. - - Infrastructure Actions repo - hosts Infrastructure-approved GH Actions that all projects can use. This generated a lot of interest and suggestions from those present, so we are devoting the next Roundtable to talking through how we will manage this repository and curate its contents. +- Apache STeVe - Voting tool for the ASF and for projects. It is its own top level project. +- Slack - A project channel in the 'the-asf' space can be a communications hub for a project rather than, say, IRC. +- Infra Reports - Dashboard covering resource uptime, public download statistics, use of GitHub Actions, the project website resource checker, and so on. +- Infrastructure Actions repo - hosts Infrastructure-approved GH Actions that all projects can use. This generated a lot of interest and suggestions from those present, so we are devoting the next Roundtable to talking through how we will manage this repository and curate its contents. We also touched on Non-Infra tools: - - Reporter (ComDev) - - Apache Whimsy +- Reporter (ComDev) +- Apache Whimsy The full notes of the meeting are at Infra Roundtable 2024-06-05, 17:00 UTC. diff --git a/content/blog/newsletter_06_25.md b/content/blog/newsletter_06_25.md index 4d42bf70b..ba644730b 100644 --- a/content/blog/newsletter_06_25.md +++ b/content/blog/newsletter_06_25.md @@ -8,11 +8,11 @@ permalink: newsletter0625 layout: post Discussions at the June Roundtable covered, among other things: - - Misuse of GitHub Actions. Projects are using, and sometimes force-pushing, tags, rather than SHAs. While there are GHA linters that can help identify problems, we should move actively to encourage projects to stop using tags in GHAs, and only use SHAs. There was discussion of the possibility of applying some sort of seal of approval on custom GHAs that comply with this requirement. - - Creating a checklist or scorecard to encourage creators to bring their custom GHAs into compliance with our requirements. - - Review of progress on repository.a.o, and Tooling's progress on the Apache Trusted Release platform. - - What PMCs can use as a password manager (at the moment, only a private repo on SVN or Git). - - Complete notes from the meeting are at Infra Roundtable 2025-06-04 1700 UTC +- Misuse of GitHub Actions. Projects are using, and sometimes force-pushing, tags, rather than SHAs. While there are GHA linters that can help identify problems, we should move actively to encourage projects to stop using tags in GHAs, and only use SHAs. There was discussion of the possibility of applying some sort of seal of approval on custom GHAs that comply with this requirement. +- Creating a checklist or scorecard to encourage creators to bring their custom GHAs into compliance with our requirements. +- Review of progress on repository.a.o, and Tooling's progress on the Apache Trusted Release platform. +- What PMCs can use as a password manager (at the moment, only a private repo on SVN or Git). +- Complete notes from the meeting are at Infra Roundtable 2025-06-04 1700 UTC The next roundtable will be **Wednesday, July 2, 1700 UTC**. Infra will pull a number of coming-soon improvements out of its hat for discussion. diff --git a/content/blog/newsletter_06_26.md b/content/blog/newsletter_06_26.md index 1cfcd9239..9db1ec3f9 100644 --- a/content/blog/newsletter_06_26.md +++ b/content/blog/newsletter_06_26.md @@ -10,8 +10,8 @@ The June Roundtable focused on **release automation**, with Piotr Karwasz presen The coming roundtables will be - - July 1, 1700 UTC. Clay Johnson of Gradle will present on **predictive test analysis**. - - August 5, 1700 UTC. The Tooling team will present the current state of the **Apache Trusted Releases (ATR) platform**. +- July 1, 1700 UTC. Clay Johnson of Gradle will present on **predictive test analysis**. +- August 5, 1700 UTC. The Tooling team will present the current state of the **Apache Trusted Releases (ATR) platform**. Details about joining a roundtable, and what goes on at one, are here: infra.apache.org/roundtable.html. @@ -31,14 +31,14 @@ The source code is at cwiki.apache.org/confluence/display/INFRA/GitHub+Actions+Recommended+Practices. diff --git a/content/blog/newsletter_07_24.md b/content/blog/newsletter_07_24.md index de2846821..73fa94af0 100644 --- a/content/blog/newsletter_07_24.md +++ b/content/blog/newsletter_07_24.md @@ -13,9 +13,9 @@ The name references the tool-maker 'Q', who provides weapons and gadgets for Age ### Qbot has an evolving set of functions: - - Providing to the channel notifications related to your project's Jira tickets - new ticket, new comment, ticket resolved. - - Adding people to private channels. - - Starting a question queue in the huddle in a channel workspace (note that this feature is in alpha development). +- Providing to the channel notifications related to your project's Jira tickets - new ticket, new comment, ticket resolved. +- Adding people to private channels. +- Starting a question queue in the huddle in a channel workspace (note that this feature is in alpha development). It also has a set of 'fun' features, such as rolling dice or flipping a coin. @@ -27,9 +27,9 @@ The July Roundtable focused on managing the new Infra's 'good ideas' repo , where others can easily comment on or extend the suggestion. diff --git a/content/blog/newsletter_07_25.md b/content/blog/newsletter_07_25.md index b488ac020..315e63a08 100644 --- a/content/blog/newsletter_07_25.md +++ b/content/blog/newsletter_07_25.md @@ -9,8 +9,8 @@ Welcome to _Inside Infra_ for July, 2025 At the July Roundtable, Daniel Gruno presented on the **catalog server**, now in development: catalog-test.apache.org/lookup/project. The plan is to move all metadata that the Foundation and projects use into one place for reference and research: - - membership details - - the details of every .asf.yaml file in use +- membership details +- the details of every .asf.yaml file in use Infra is working in tandem with the Tooling team to develop this service. We are assembling the list of metadata at the moment. When the service is complete, you will, we hope, have one place to go to find ASF-related information you need. diff --git a/content/blog/newsletter_08_25.md b/content/blog/newsletter_08_25.md index 28f49e23c..11f5161ab 100644 --- a/content/blog/newsletter_08_25.md +++ b/content/blog/newsletter_08_25.md @@ -11,11 +11,11 @@ The August Roundtable discussed the impact of **AI scraping** on The ASF, and wh The main impacts on ASF infrastructure are: - - Overuse of resources - effectively, distributed denial of service - - Increased downtime - - Valid requestors unable to reach resources - - Alerts at all hours of the day and night for limited staff - - Possible legal exposure relative to PII being scraped +- Overuse of resources - effectively, distributed denial of service +- Increased downtime +- Valid requestors unable to reach resources +- Alerts at all hours of the day and night for limited staff +- Possible legal exposure relative to PII being scraped The full summary, including many helpful comments and suggestions, is at Infra Roundtable 2025-08-06 1700 UTC diff --git a/content/blog/newsletter_09_25.md b/content/blog/newsletter_09_25.md index 0d5118e8b..afa840196 100644 --- a/content/blog/newsletter_09_25.md +++ b/content/blog/newsletter_09_25.md @@ -23,10 +23,10 @@ Information about how to take part in the online roundtables is at November 6 - - November 13 +- November 6 +- November 13 ## December roundtable @@ -33,8 +33,8 @@ _Myrle Krantz_ A two-part interview with Chris Lambertus is here: - - part one - - part two +- part one +- part two ## ASF Writers diff --git a/content/blog/responding_to_2024_survey.md b/content/blog/responding_to_2024_survey.md index 7f314e471..3b8426217 100644 --- a/content/blog/responding_to_2024_survey.md +++ b/content/blog/responding_to_2024_survey.md @@ -11,55 +11,55 @@ The comments and suggestions fell into several broad categories: ### Communications - - **Periodic newsletter** -"Inside Infra" goes monthly to all members of the users@infra mailing list and is available here in the Infra Blog. - - **Periodic publication** of the basic stuff, such as 'Where is self-serve?' - We include handy hints in the newsletter. - - **Email announcements of important matters to all members** - We try to balance keeping people informed and not flooding inboxes. - - **Better connection of each Infra service with its documentation** - Reviewing ...INFRA-27577 - - **News box on the landing page at infra.a.o needs to be updated more frequently**  - implemented - - **Questions to `users@infra.a.o` seem to go unanswered** - Questions seem to get a response within 24 hours in almost all cases - - **Be more consistent in showing latest and earlier versions of info on the wiki pages** - We have the most current information at the top of the wiki page, and display any older information (perhaps related to a still-valid but no longer recommended process) that we feel is necessary to preserve at the bottom of the page, with a note indicating the build or situation this older information relates to. We have no policy of retaining wiki information that is no longer needed. - - **Public archive containing summaries of all main points in all roundtables**  - this exists at Infra Roundtable - - **Archived blog content is greatly bit rotted with no way to fix; no good modern blogging options** - Blog content is intended to be permanent. 'Archived' is archived and dated. When there is a possibility of confusion due to statements in a past blog entry, Infra adds a note at the top to indicate the current state of play. - - **Mailing list noise from GitHub/GitBox. Drop messages from some bots** - "Projects can set their notification targets for commits and GitHub issues/PRs/actions and discussions via .asf.yaml." See github.com/apache/infrastructure-asfyaml?tab=readme-ov-file#notif +- **Periodic newsletter** -"Inside Infra" goes monthly to all members of the users@infra mailing list and is available here in the Infra Blog. +- **Periodic publication** of the basic stuff, such as 'Where is self-serve?' - We include handy hints in the newsletter. +- **Email announcements of important matters to all members** - We try to balance keeping people informed and not flooding inboxes. +- **Better connection of each Infra service with its documentation** - Reviewing ...INFRA-27577 +- **News box on the landing page at infra.a.o needs to be updated more frequently**  - implemented +- **Questions to `users@infra.a.o` seem to go unanswered** - Questions seem to get a response within 24 hours in almost all cases +- **Be more consistent in showing latest and earlier versions of info on the wiki pages** - We have the most current information at the top of the wiki page, and display any older information (perhaps related to a still-valid but no longer recommended process) that we feel is necessary to preserve at the bottom of the page, with a note indicating the build or situation this older information relates to. We have no policy of retaining wiki information that is no longer needed. +- **Public archive containing summaries of all main points in all roundtables**  - this exists at Infra Roundtable +- **Archived blog content is greatly bit rotted with no way to fix; no good modern blogging options** - Blog content is intended to be permanent. 'Archived' is archived and dated. When there is a possibility of confusion due to statements in a past blog entry, Infra adds a note at the top to indicate the current state of play. +- **Mailing list noise from GitHub/GitBox. Drop messages from some bots** - "Projects can set their notification targets for commits and GitHub issues/PRs/actions and discussions via .asf.yaml." See github.com/apache/infrastructure-asfyaml?tab=readme-ov-file#notif ### Technical services - - **Proactively improve the security posture of all ASF projects** - Infra is working on many fronts to enhance the security of all ASF and ASF project assets and servers. This work is never complete, because the threats constantly evolve. VP-Security is responsible for creating security policies for ASF projects to follow. - - **Automating releases** - this is coming in 2026 with the Apache Trusted Release service. - - **FreeBSD runners and CI builder on GitHub** - It may be an option to think about if GitHub can provide hosting, or if projects needing this can bring their own runners. - - **More docs and examples for VM setup via puppet** - ASF committers can consult the `infrastructure-p6` GitHub repository for code examples. - - **Password management solution** - Infra has not made progress on this service. - - **More powerful GitHub Action runners for all platforms** - More powerful comes at a cost: GitHub charges for those. if projects can get donated self-hosted or 'runs-on' runners, Infra can hook them up. - - **Video call service** - Desirable. Neither Infra nor Tooling are working on such a service at the moment. - - **ASF project websites vary widely in visual appeal and functionality. How to make it easier to quickly set up ‘modern looking’ websites?** - Perhaps for a new ASF project, or community.a.o , or another, a global provided style that can built in different ways would indeed be nice (such as Forrest from old, Maven, etc.). We do have Pelican-enabled builds that can build a consistent look, but the tool remains hard to use currently. - - **Fix tool sprawl – self-serve, whimsy, reporter, cveprocess...** - These are separate tools for separate services, and often run by different volunteer projects or committees. Infra is not in charge of many of these services. - - **Issue tracking – automated scripts to migrate existing issues from Jira to GitHub Issues** - Infra offers a service to do this for projects using the jira-issues-importer tool, and projects like Maven and others have written their own tools. - - **Research an official Stack Overflow integration as an alternative to users’ lists?** - Infra has been looking into this. But nothing determined yet. - - **Easy to use and secure package and releasing platform** - the Apache Trusted Release service, which will provide this, is in the beta-test phase - - **FreeBSD/BSD** - They are no longer an option. - - **Automated voting tool** - Apache STeVe is available for PMC votes; the Apache Trusted Release service, which will have this feature for voting on releases, is in the beta-test phase. +- **Proactively improve the security posture of all ASF projects** - Infra is working on many fronts to enhance the security of all ASF and ASF project assets and servers. This work is never complete, because the threats constantly evolve. VP-Security is responsible for creating security policies for ASF projects to follow. +- **Automating releases** - this is coming in 2026 with the Apache Trusted Release service. +- **FreeBSD runners and CI builder on GitHub** - It may be an option to think about if GitHub can provide hosting, or if projects needing this can bring their own runners. +- **More docs and examples for VM setup via puppet** - ASF committers can consult the `infrastructure-p6` GitHub repository for code examples. +- **Password management solution** - Infra has not made progress on this service. +- **More powerful GitHub Action runners for all platforms** - More powerful comes at a cost: GitHub charges for those. if projects can get donated self-hosted or 'runs-on' runners, Infra can hook them up. +- **Video call service** - Desirable. Neither Infra nor Tooling are working on such a service at the moment. +- **ASF project websites vary widely in visual appeal and functionality. How to make it easier to quickly set up ‘modern looking’ websites?** - Perhaps for a new ASF project, or community.a.o , or another, a global provided style that can built in different ways would indeed be nice (such as Forrest from old, Maven, etc.). We do have Pelican-enabled builds that can build a consistent look, but the tool remains hard to use currently. +- **Fix tool sprawl – self-serve, whimsy, reporter, cveprocess...** - These are separate tools for separate services, and often run by different volunteer projects or committees. Infra is not in charge of many of these services. +- **Issue tracking – automated scripts to migrate existing issues from Jira to GitHub Issues** - Infra offers a service to do this for projects using the jira-issues-importer tool, and projects like Maven and others have written their own tools. +- **Research an official Stack Overflow integration as an alternative to users’ lists?** - Infra has been looking into this. But nothing determined yet. +- **Easy to use and secure package and releasing platform** - the Apache Trusted Release service, which will provide this, is in the beta-test phase +- **FreeBSD/BSD** - They are no longer an option. +- **Automated voting tool** - Apache STeVe is available for PMC votes; the Apache Trusted Release service, which will have this feature for voting on releases, is in the beta-test phase. ### Jenkins There were a number of questions for which the most accurate answers are available at `https://www.jenkins.io/doc/` - - **In CI/CD, we don’t really have any CD. Where can we deploy test apps?** – Infra does not offer CD at the moment. Some projects may be able to host a test version of their apps on their virtual machines, but this may not be practical for our more complex products, and not meaningful for others. - - **Need a simple build caching solution for Jenkins so we can cache Maven repositories between builds** – Maven has a build cache tool now. - - **Jenkins builds should be containerized and isolated from one another, so one build does not bring down a node for everybody else. Need guaranteed minimum performance for performance-sensitive build tests.** – Some projects have secured donations of resources to ensure exclusive build controller and nodes. The rest of us have to share our limited resources. - - **Long build queues on ASF Jenkins; problems with GHA builds** - Long build queues are not common any more. We have managed huge improvements to Jenkins build nodes in particular. - - **Jenkins seems outdated. Would prefer something like Concourse.** - Opinions differ. Infra offers Jenkins, but it is not compulsory to use. - - **More stability for Ubuntu Jenkins nodes** - We have made great strides in the Jenkins CI arena over the last two years and build nodes are pretty stable these days. +- **In CI/CD, we don’t really have any CD. Where can we deploy test apps?** – Infra does not offer CD at the moment. Some projects may be able to host a test version of their apps on their virtual machines, but this may not be practical for our more complex products, and not meaningful for others. +- **Need a simple build caching solution for Jenkins so we can cache Maven repositories between builds** – Maven has a build cache tool now. +- **Jenkins builds should be containerized and isolated from one another, so one build does not bring down a node for everybody else. Need guaranteed minimum performance for performance-sensitive build tests.** – Some projects have secured donations of resources to ensure exclusive build controller and nodes. The rest of us have to share our limited resources. +- **Long build queues on ASF Jenkins; problems with GHA builds** - Long build queues are not common any more. We have managed huge improvements to Jenkins build nodes in particular. +- **Jenkins seems outdated. Would prefer something like Concourse.** - Opinions differ. Infra offers Jenkins, but it is not compulsory to use. +- **More stability for Ubuntu Jenkins nodes** - We have made great strides in the Jenkins CI arena over the last two years and build nodes are pretty stable these days. ### Docker - - **More control over Docker Hub repos** - A selfserve tool for creating dockerhub repos, adding/removing members, etc. is in the works. - - **CI stability** - We have made huge improvements, and we continue to improve and expand our CI offering. - - **Docker Images** - Docker Hub repos managed by infra for projects, and self service, coming for this. +- **More control over Docker Hub repos** - A selfserve tool for creating dockerhub repos, adding/removing members, etc. is in the works. +- **CI stability** - We have made huge improvements, and we continue to improve and expand our CI offering. +- **Docker Images** - Docker Hub repos managed by infra for projects, and self service, coming for this. ### Builds - - **Builds are sometimes flaky because of disk-full error, broken hardware, missing build tools...** - The Tooling team is hoping to help with these issues in the new Apache Trusted Release platform, which is in beta-test. - - **Builds are very slow for projects with a large number of modules and different workflows for different test suites. Such projects need more dedicated resources.** - Projects that need additional resources may need to search for a donor or take the request to the Board. Infra does not have sufficient resources to get every project's builds into the comfort zone. - - **Struggling to find good documentation on Buildbot hosts, in particular for setting up a Windows build.** - Agree - we do have Buildbot documentation, but it can do with improvements. +- **Builds are sometimes flaky because of disk-full error, broken hardware, missing build tools...** - The Tooling team is hoping to help with these issues in the new Apache Trusted Release platform, which is in beta-test. +- **Builds are very slow for projects with a large number of modules and different workflows for different test suites. Such projects need more dedicated resources.** - Projects that need additional resources may need to search for a donor or take the request to the Board. Infra does not have sufficient resources to get every project's builds into the comfort zone. +- **Struggling to find good documentation on Buildbot hosts, in particular for setting up a Windows build.** - Agree - we do have Buildbot documentation, but it can do with improvements. Infra plans to run the next version of its survey sometime in 2026. diff --git a/content/blog/the_joy_of_feedback.md b/content/blog/the_joy_of_feedback.md index d97fbe40a..8eccd4d4b 100644 --- a/content/blog/the_joy_of_feedback.md +++ b/content/blog/the_joy_of_feedback.md @@ -5,9 +5,9 @@ layout: post In discussions at ApacheCon in New Orleans, we learned that the three standard methods of communicating with Infra: - * opening a Jira ticket - * sending an email - * posting a message on the `#asfinfra` Slack channel +* opening a Jira ticket +* sending an email +* posting a message on the `#asfinfra` Slack channel are not ideal for many conversations folks would like to have about The ASF's infrastructure. @@ -38,4 +38,4 @@ Surveys will be anonymous and results will be posted on the Infra blog. Dependin Cheers, - - ASF Infra +* ASF Infra diff --git a/content/blog/trivy_security_incident.md b/content/blog/trivy_security_incident.md index c63e93e8b..65d40a1d1 100644 --- a/content/blog/trivy_security_incident.md +++ b/content/blog/trivy_security_incident.md @@ -8,8 +8,8 @@ Trivy, Agua Security's open-source vulnerability scanner, appears to have experi ASF Infrastructure and ASF Security have provided the following summary based on what we believe to be true: - - Trivy version 0.69.4 contained malicious code that could potentially steal credentials present in GitHub Secrets. - - The trivy-action GitHub Action and trivy-setup were also compromised. +- Trivy version 0.69.4 contained malicious code that could potentially steal credentials present in GitHub Secrets. +- The trivy-action GitHub Action and trivy-setup were also compromised. On March 21, Trivy published this statement about the event. @@ -19,9 +19,9 @@ A small number of ASF projects include the trivy GitHub Action in their build wo ### Infra response - - ASF Infra and ASF Security agreed to disable all previously allowed "verified creator" actions while the incident is being investigated - - This may cause build failures, and require projects request newly-failed actions be added via the Infra GHA approval process: github.com/apache/infrastructure-actions?tab=readme-ov-file#adding-a-new-version-to-the-allow-list - - Infra and the Security team are investigating if any secrets and Git repositories of ASF projects may have been compromised. +- ASF Infra and ASF Security agreed to disable all previously allowed "verified creator" actions while the incident is being investigated +- This may cause build failures, and require projects request newly-failed actions be added via the Infra GHA approval process: github.com/apache/infrastructure-actions?tab=readme-ov-file#adding-a-new-version-to-the-allow-list +- Infra and the Security team are investigating if any secrets and Git repositories of ASF projects may have been compromised. ### For further information diff --git a/content/pages/account-mgmt.md b/content/pages/account-mgmt.md index 6ed929163..a76b0e114 100644 --- a/content/pages/account-mgmt.md +++ b/content/pages/account-mgmt.md @@ -31,16 +31,16 @@ This should decrypt the file and display the output in the window. 4. If that didn't work, email `root@`. In your email, mention the following information: - - Your username. - - The fact that you have tried a self-service password reset, and why it didn't work. (Was the mail received? Did you decrypt it successfully?) - - Why you need to regain access to your Apache account -- e.g., if it is to work on a foundation project, name that project; or if you are a foundation member, state that. - - SSH access to a project VM via public-key authentication. - - Whether you ever set up Orthrus/OPIE on any `*.apache.org` box. (This is only applicable to people who had root permissions on PMC VMs.) - - Whether you have access to the private part of a PGP key associated with your Apache account. - - Whether the contact information on your ICLA is valid. - - For (ASF Members only, whether the contact information in your `members.txt` entry is valid. - - Whether you are able to send a new ICLA, with the same signature as your original one, which specifies new contact information. - - Whether there is any other way in which we (Infra) might satisfy ourselves that you are the legitimate owner of that account. +- Your username. +- The fact that you have tried a self-service password reset, and why it didn't work. (Was the mail received? Did you decrypt it successfully?) +- Why you need to regain access to your Apache account -- e.g., if it is to work on a foundation project, name that project; or if you are a foundation member, state that. +- SSH access to a project VM via public-key authentication. +- Whether you ever set up Orthrus/OPIE on any `*.apache.org` box. (This is only applicable to people who had root permissions on PMC VMs.) +- Whether you have access to the private part of a PGP key associated with your Apache account. +- Whether the contact information on your ICLA is valid. +- For (ASF Members only, whether the contact information in your `members.txt` entry is valid. +- Whether you are able to send a new ICLA, with the same signature as your original one, which specifies new contact information. +- Whether there is any other way in which we (Infra) might satisfy ourselves that you are the legitimate owner of that account. **Note**: please do not ask other ASF committers or Members to email root@ to vouch for you. diff --git a/content/pages/app-upgrade-policy.md b/content/pages/app-upgrade-policy.md index 947a24ca2..4840dc8e6 100644 --- a/content/pages/app-upgrade-policy.md +++ b/content/pages/app-upgrade-policy.md @@ -45,12 +45,12 @@ Every two months we perform upgrades to plugins that are compatible with the ver Infra documents what we upgraded and when, from what version to what version, on these pages: - - Jenkins upgrades - - Jenkins plugin upgrades - - Jira upgrades - - Jira plugin upgrades - - Confluence upgrades - - Confluence plugin upgrades +- Jenkins upgrades +- Jenkins plugin upgrades +- Jira upgrades +- Jira plugin upgrades +- Confluence upgrades +- Confluence plugin upgrades # Notifications diff --git a/content/pages/apple-dev-program.md b/content/pages/apple-dev-program.md index 7ce3e056b..e21a1163a 100644 --- a/content/pages/apple-dev-program.md +++ b/content/pages/apple-dev-program.md @@ -7,9 +7,9 @@ Apple has granted a fee-waiver to participants in Apache Software Foundation pro To join the Apple Developer Program as part of the ASF, committers must: - - create an Apple ID using their @apache.org e-mail address - - create a Jira ticket for Infra under the code-signing component to request that Infra add them to the list of ASF participants - - read the latest Apple Developer Program Agreement - - confirm, once Infra has added their name to the participants' list, that they have read, understood and agree to abide by the terms of the Apple Developer Program Agreement +- create an Apple ID using their @apache.org e-mail address +- create a Jira ticket for Infra under the code-signing component to request that Infra add them to the list of ASF participants +- read the latest Apple Developer Program Agreement +- confirm, once Infra has added their name to the participants' list, that they have read, understood and agree to abide by the terms of the Apple Developer Program Agreement The file that tracks participants' confirmations, with additional information for updating it, is here. diff --git a/content/pages/asf-pelican-data.md b/content/pages/asf-pelican-data.md index 54973355f..51a9c9a2e 100644 --- a/content/pages/asf-pelican-data.md +++ b/content/pages/asf-pelican-data.md @@ -643,9 +643,9 @@ def split_list(metadata, seq, reference, split): Before you code to add a data source, evaluate which of the above patterns it fits. - - Is it a custom pattern as for Twitter, blogs, and ECCN? - - Can it follow the sequence of directives used for committee iInfo? - - If it is a sequence of directives, does it need a new one? +- Is it a custom pattern as for Twitter, blogs, and ECCN? +- Can it follow the sequence of directives used for committee iInfo? +- If it is a sequence of directives, does it need a new one? ### Adding a custom data source diff --git a/content/pages/asf-pelican-gettingstarted.md b/content/pages/asf-pelican-gettingstarted.md index 5ca2cb392..f7026a310 100644 --- a/content/pages/asf-pelican-gettingstarted.md +++ b/content/pages/asf-pelican-gettingstarted.md @@ -74,8 +74,8 @@ The `.ezmd` files in the template's `content` directory show examples, and ezt template into GFM and then to HTML. - * .ezmd + - .ezmd ## Content init (content_object_init) This is signaled after a reader has processed the site's content. At this point plugins can review, record, and transform the HTML content. - The asfgenid plugin, `./asfgenid.py`, performs a number of steps. Some of the steps are optional. - * Metadata transformation by looking up {{ key_expression }} in the page metadata. - * Inventory of existing ID attributes. - * Set ID and class attributes specified by {#id} and {.class} syntax. - * Assign an ID to any headings without IDs. - * Insert a table of contents if a [TOC] tag is present. + - Metadata transformation by looking up {{ key_expression }} in the page metadata. + - Inventory of existing ID attributes. + - Set ID and class attributes specified by {#id} and {.class} syntax. + - Assign an ID to any headings without IDs. + - Insert a table of contents if a [TOC] tag is present. ## Apache CMS diff --git a/content/pages/asf-pelican.md b/content/pages/asf-pelican.md index 02dcd2eee..50ca16e37 100644 --- a/content/pages/asf-pelican.md +++ b/content/pages/asf-pelican.md @@ -13,14 +13,14 @@ See the [Pelican getting-started guide](asf-pelican-gettingstarted.html). ## For site designers -- Information about the [ASF Theme](asf-pelican-theme.html). -- The Apache Project Website Checker periodically reviews all TLP websites and reports whether they comply with Apache's policies for TLP websites. +- Information about the [ASF Theme](asf-pelican-theme.html). +- The Apache Project Website Checker periodically reviews all TLP websites and reports whether they comply with Apache's policies for TLP websites. ## For site developers -- [Data modeling](asf-pelican-data.html) provides what developers need to know to maintain and expand on the data they want to use and display on their site. -- [Build process](asf-pelican-build.html) describes the full end-to-end build from the developer's perspective. -- Review the [plugins](asf-pelican-plugins.html) that are included in the template repository, and the plugin architecture. +- [Data modeling](asf-pelican-data.html) provides what developers need to know to maintain and expand on the data they want to use and display on their site. +- [Build process](asf-pelican-build.html) describes the full end-to-end build from the developer's perspective. +- Review the [plugins](asf-pelican-plugins.html) that are included in the template repository, and the plugin architecture. ## For site committers diff --git a/content/pages/asf-yaml.md b/content/pages/asf-yaml.md index 84b5a5b07..f13bc4d08 100644 --- a/content/pages/asf-yaml.md +++ b/content/pages/asf-yaml.md @@ -3,10 +3,10 @@ license: https://www.apache.org/licenses/LICENSE-2.0 `.asf.yaml` is a branch-specific YAML configuration file that a project may create (using a text editor of your choice) and put in the root of a Git repository to control features such as - - notification schemes - - website staging - - GitHub settings - - Pelican builds +- notification schemes +- website staging +- GitHub settings +- Pelican builds It operates on a per-branch basis, meaning you can have different settings for different branches, and only those with an active `.asf.yaml` file will kick off a feature. Metadata settings (repo settings, features, labels) are not branch-dependent and should exist in the main (default) branch. diff --git a/content/pages/asfbot.md b/content/pages/asfbot.md index 105329b1e..3f62b5c01 100644 --- a/content/pages/asfbot.md +++ b/content/pages/asfbot.md @@ -9,12 +9,12 @@ ASFBot offers many services for Apache projects on Internet Relay Chat (IRC). IR ## Contents ## - - Reporting on repository commits and new Jira tickets - - Reporting on changes to Jira tickets - - Fetching issue information - - Secretary feature - - Record-keeping for meetings - - Technical information +- Reporting on repository commits and new Jira tickets +- Reporting on changes to Jira tickets +- Fetching issue information +- Secretary feature +- Record-keeping for meetings +- Technical information

Reporting on repository commits and new Jira tickets

@@ -50,13 +50,13 @@ ASFBot can keep a record of meetings you hold on IRC and publish these in HTML f Record keeping works as follows: - - To initiate a meeting, type `ASFBot: meeting start`. - - To set an agenda,type `#topic [agenda goes here]` or use the `/topicmeetbot commands, so `#meetingstart` and `#meetingend` will also start and end a recording of a meeting. diff --git a/content/pages/asfquart.md b/content/pages/asfquart.md index ff642264d..9ac78bc61 100644 --- a/content/pages/asfquart.md +++ b/content/pages/asfquart.md @@ -5,11 +5,11 @@ ASFQuart is an asynchronous Python web microframework, a customization of github.com/apache/infrastructure-asfquart. diff --git a/content/pages/atr.md b/content/pages/atr.md index e1b3d9c64..859ae6b21 100644 --- a/content/pages/atr.md +++ b/content/pages/atr.md @@ -5,8 +5,8 @@ license: https://www.apache.org/licenses/LICENSE-2.0 The Apache Trusted Releases (ATR) platform performs two key functions: - - it simplifies the process of preparing and approving a PMC's release of code - - it strengthens security around the release process so that both the project releasing the code and the users downloading it can be confident that the package contains only what it should +- it simplifies the process of preparing and approving a PMC's release of code +- it strengthens security around the release process so that both the project releasing the code and the users downloading it can be confident that the package contains only what it should In August 2026, ATR is moving into **beta testing**. Once it is fully functional and the beta is in process, its documentation will be available at release-test.apache.org/docs/introduction-to-atr. diff --git a/content/pages/backup-policy.md b/content/pages/backup-policy.md index 89b1b6678..00cee2bd6 100644 --- a/content/pages/backup-policy.md +++ b/content/pages/backup-policy.md @@ -11,21 +11,21 @@ Foundation Critical systems receive additional nightly rsync/zfs based snapshots #### Databases #### - - MySQL and Postgres databases are backed up nightly using a puppet managed tool to /x1/db_dump - - /x1/db_dump is picked up by the rsync or backuppc process +- MySQL and Postgres databases are backed up nightly using a puppet managed tool to /x1/db_dump +- /x1/db_dump is picked up by the rsync or backuppc process #### Software repositories #### - - gitbox.a.o (rsync, backuppc, GitHub mirrors). - - svn.a.o (rsync, backuppc, azure DR replica). - - archive.a.o (backuppc). +- gitbox.a.o (rsync, backuppc, GitHub mirrors). +- svn.a.o (rsync, backuppc, azure DR replica). +- archive.a.o (backuppc). #### Server logs #### - - Ephemeral. retained in Elasticsearch for approximately 90 days, but not guaranteed. Not available outside Infra. - - Compiled statistics available in some cases. +- Ephemeral. retained in Elasticsearch for approximately 90 days, but not guaranteed. Not available outside Infra. +- Compiled statistics available in some cases. #### Email #### - - Raw archives (mbox-vm) (rsync/backuppc) - - qmail source (hermes) (rsync backup + rsync replica) +- Raw archives (mbox-vm) (rsync/backuppc) +- qmail source (hermes) (rsync backup + rsync replica) diff --git a/content/pages/bug-writing-guide.md b/content/pages/bug-writing-guide.md index 55be66430..e28b36207 100644 --- a/content/pages/bug-writing-guide.md +++ b/content/pages/bug-writing-guide.md @@ -1,12 +1,12 @@ Title: Writing a good bug report license: https://www.apache.org/licenses/LICENSE-2.0 - - Bug reporting - - Bug-tracking systems - - Is this a new bug? - - A useful bug report - - If your report or comment gets blocked - - Following up +- Bug reporting +- Bug-tracking systems +- Is this a new bug? +- A useful bug report +- If your report or comment gets blocked +- Following up

Bug reporting

@@ -20,8 +20,8 @@ For the purposes of this discussion, we'll call any issue, from a calculation er ASF has two bug-tracking systems: - - Jira - - Bugzilla +- Jira +- Bugzilla Infra itself uses Jira (requires login). @@ -39,8 +39,8 @@ If what you found seems to be a new bug, you get to report it! Useful bug reports get bugs fixed. A useful bug report is usually: - - Reproducible. If a developer or sysadmin can't see it or conclusively prove that it exists, they may stamp it "WORKSFORME" or "INVALID", and move on to the next bug. Every detail you can provide helps. - - Specific. The quicker the person looking at your report can connect your issue to a specific problem, the quicker they can fix it. +- Reproducible. If a developer or sysadmin can't see it or conclusively prove that it exists, they may stamp it "WORKSFORME" or "INVALID", and move on to the next bug. Every detail you can provide helps. +- Specific. The quicker the person looking at your report can connect your issue to a specific problem, the quicker they can fix it. Let's say the application you're testing is a web browser. You crash at foo.com, and want to write up a bug report: @@ -63,8 +63,8 @@ The bug-tracking systems allow you to suggest a **severity** for the bug. If you Make sure you provide a useful **title** for the report: - - Useful: "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589" - - Not useful: "Browser crashes" or "Install problem" +- Useful: "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589" +- Not useful: "Browser crashes" or "Install problem" Review [Creating a Jira ticket](jira-guidelines.html) for specifics about Jira bug reports. diff --git a/content/pages/build-supported-services.md b/content/pages/build-supported-services.md index f6ebe0d50..d7d913720 100644 --- a/content/pages/build-supported-services.md +++ b/content/pages/build-supported-services.md @@ -8,16 +8,16 @@ Here is a summary of The ASF's 'build' (CI/CD) and related services, those hoste Note that 'supported' means that Infra provides the service or provides access to the service. It does not mean that a particular service is considered an official 'release channel'. -- Jenkins -- Buildbot -- Apache Gump -- GitHub Actions -- Artifactory -- Nexus -- Nightlies -- DockerHub -- Gradle Enterprise -- Sonarcloud +- Jenkins +- Buildbot +- Apache Gump +- GitHub Actions +- Artifactory +- Nexus +- Nightlies +- DockerHub +- Gradle Enterprise +- Sonarcloud

Jenkins

@@ -45,8 +45,8 @@ ASF Infra runs an instance of the open source Buildbot software. Buildbot runs o Projects can add/edit/remove their configuration files via Subversion or Git. - - Subversion - - Git/GitHub +- Subversion +- Git/GitHub Use the standard naming `$projectname.py` for your config file. You may place multiple build jobs in this file. @@ -101,10 +101,10 @@ All Committers have access to GHA and their workflows via `commit` using their L In addition to the official GitHub documentation, Infra maintains: - - [GitHub Actions and Secrets](github-actions-secrets.html), for handling credentials in workflows. - - The [GitHub Actions Policy](github-actions-policy.html), which sets the limits and requirements every ASF workflow must meet. - - [GitHub Actions](services.html#github-actions) on the Services and Tools page, which explains why the shared runner queues build up and how your project can help. - - The GitHub Actions Recommended Practices wiki page (requires a committer or Member login). +- [GitHub Actions and Secrets](github-actions-secrets.html), for handling credentials in workflows. +- The [GitHub Actions Policy](github-actions-policy.html), which sets the limits and requirements every ASF workflow must meet. +- [GitHub Actions](services.html#github-actions) on the Services and Tools page, which explains why the shared runner queues build up and how your project can help. +- The GitHub Actions Recommended Practices wiki page (requires a committer or Member login).

Artifactory

@@ -153,10 +153,10 @@ The ASF has an 'apache' account at GitHub Actions to DockerHub +- GitHub Actions to DockerHub

Gradle Enterprise

Gradle is a suite of acceleration and analytics technologies for CI/CD systems to help projects identify and analyze trends while optimizing build resources. The result is faster builds, with fewer failures, The ASF instance of Gradle enterprise is at develocity.apache.org. diff --git a/content/pages/code-signing-access.md b/content/pages/code-signing-access.md index bd8a7c352..18178b939 100644 --- a/content/pages/code-signing-access.md +++ b/content/pages/code-signing-access.md @@ -5,17 +5,17 @@ The ASF currently uses ssl.com Jira ticket with the following information: - - Set the component to `code signing` - - The name of the PMC requesting the code signing service - - The Apache IDs of the committer(s) who will act as release managers +- Set the component to `code signing` +- The name of the PMC requesting the code signing service +- The Apache IDs of the committer(s) who will act as release managers The infra team will then request the account creation and (after a few e-mails and configuring a OTP token) you will have an account that lets you access the service. Each PMC member must have their own account to access the service. Release managers can then sign release artifacts via: - - the API using a tool such as Jsign - - the standard Windows tools (signtool.exe / certutil.exe) by installing the eSigner Cloud Key Adapter (CKA) - - ssl.com's Java based CodeSignTool - - the eSigner web interface +- the API using a tool such as Jsign +- the standard Windows tools (signtool.exe / certutil.exe) by installing the eSigner Cloud Key Adapter (CKA) +- ssl.com's Java based CodeSignTool +- the eSigner web interface For the first three options, the code signing is performed locally (no need to upload large files, just the hashes are passed to the central signing service). diff --git a/content/pages/committer-outreach.md b/content/pages/committer-outreach.md index 90978e928..725b9cc76 100644 --- a/content/pages/committer-outreach.md +++ b/content/pages/committer-outreach.md @@ -12,8 +12,8 @@ channels for reaching the Foundation's Committers. # Coverage - - For general communications, it is easiest to reach Committers via the `committers@` +- For general communications, it is easiest to reach Committers via the `committers@` mailing list - - All members of all PMCs (which includes many, but not all, Committers) are subscribed automatically to the `announce@infra` mailing list, and that is where to send important announcements related to infrastructure events such as outages, new services, and services being retired. - - On occasion it makes more sense to send emails directly to the affected Committers. - - Several Slack channels, such as `asfinfra` and `announcements`, are useful for delivering a version of the email message you are sending. The Slack message may reach some people more quickly. +- All members of all PMCs (which includes many, but not all, Committers) are subscribed automatically to the `announce@infra` mailing list, and that is where to send important announcements related to infrastructure events such as outages, new services, and services being retired. +- On occasion it makes more sense to send emails directly to the affected Committers. +- Several Slack channels, such as `asfinfra` and `announcements`, are useful for delivering a version of the email message you are sending. The Slack message may reach some people more quickly. diff --git a/content/pages/committers.md b/content/pages/committers.md index 7568a22c1..38ad8376c 100644 --- a/content/pages/committers.md +++ b/content/pages/committers.md @@ -39,12 +39,12 @@ As an ASF volunteer, you have the right to set your own priorities and do the wo More specific responsibilities of Committers include: - - **Deciding on release plans and releases**: A prime committer responsibility is to help decide when a version of product code is ready for release. A release is not to be taken lightly; each release must uphold the ASF tradition of quality. Each Project Management Committee PMC) formally authorizes the distribution of releases to the public. - - **Applying patches**: To grow and maintain healthy communities, committers need to discuss, review and apply patches submitted by contributors and other committers. Committers are also responsible for the quality and IP clearance of the code that goes into ASF repositories. - - **Helping users**: Committers should monitor both the `dev@` and `user@` or `users@` email lists for the projects they work on and together provide prompt and useful +- **Deciding on release plans and releases**: A prime committer responsibility is to help decide when a version of product code is ready for release. A release is not to be taken lightly; each release must uphold the ASF tradition of quality. Each Project Management Committee PMC) formally authorizes the distribution of releases to the public. +- **Applying patches**: To grow and maintain healthy communities, committers need to discuss, review and apply patches submitted by contributors and other committers. Committers are also responsible for the quality and IP clearance of the code that goes into ASF repositories. +- **Helping users**: Committers should monitor both the `dev@` and `user@` or `users@` email lists for the projects they work on and together provide prompt and useful responses to questions from users and their developer colleagues. - - **Monitoring commits and issues**: Committers should review commit email messages for their projects and point out anything that looks funny or that may point to IP issues. Committers also monitor the project's issue-tracking system (Bugzilla or Jira or something else) for bug reports or enhancement requests. - - **Helping out with the website**: The main ASF website and the project websites are in constant need of maintenance. Committers on a project are expected to +- **Monitoring commits and issues**: Committers should review commit email messages for their projects and point out anything that looks funny or that may point to IP issues. Committers also monitor the project's issue-tracking system (Bugzilla or Jira or something else) for bug reports or enhancement requests. +- **Helping out with the website**: The main ASF website and the project websites are in constant need of maintenance. Committers on a project are expected to collectively maintain the project's web site. Apache committers as a group share the responsibility to maintain the main Apache site.

Is there a set term for acting as a Committer? Will I have to be elected again?

@@ -76,13 +76,13 @@ There are many things that the PMC or PMC chair can do directly, thereby easing

How does Infra communicate with the public?

- - Infra provides status pages where you can check uptime statistics and possible outages, website source scans, and other information. - - Announcements of scheduled outages and alerts of service interruptions go to the `announce@infra.apache.org` mailing list. - - Infra uses the `users@infra.apache.org` mailing list to discuss infrastructure developments at the ASF. - - For general announcements regarding services and the like, Infra has a blog. - - Infra publishes a monthly newsletter which appears on the blog, and which we send to all subscribers to the `users@infra` email list. - - Those with access to the ASF space on Slack can enage with Infra in the `asfinfra` channel. - - On the first Wednesday of most months, Infra holds a roundtable which, in addition to a presentation, usually has time for people to raise issues or ask questions. The roundtable takes place in a Slack channel: here is information on taking part in roundtables. +- Infra provides status pages where you can check uptime statistics and possible outages, website source scans, and other information. +- Announcements of scheduled outages and alerts of service interruptions go to the `announce@infra.apache.org` mailing list. +- Infra uses the `users@infra.apache.org` mailing list to discuss infrastructure developments at the ASF. +- For general announcements regarding services and the like, Infra has a blog. +- Infra publishes a monthly newsletter which appears on the blog, and which we send to all subscribers to the `users@infra` email list. +- Those with access to the ASF space on Slack can enage with Infra in the `asfinfra` channel. +- On the first Wednesday of most months, Infra holds a roundtable which, in addition to a presentation, usually has time for people to raise issues or ask questions. The roundtable takes place in a Slack channel: here is information on taking part in roundtables.

What hosts/machines at Apache can I access?

@@ -94,7 +94,7 @@ Note that you only have SFTP access. There is no shell access.

Is there a way to see a graph of loads (CPU, I/O, network)?

- - Infra publishes top-level statistics on the status page. +- Infra publishes top-level statistics on the status page.

What should I do if Host Key has changed when logging into an Apache server?

@@ -183,12 +183,12 @@ This information has moved [here](mailing-list-moderation.html). **Note:** While there is not an official list, the following principles have been cited as the core beliefs of The Apache Way: - - collaborative software development - - commercial-friendly standard license - - consistently high quality software - - respectful, honest, technical-based interaction - - faithful implementation of standards - - security as a mandatory feature +- collaborative software development +- commercial-friendly standard license +- consistently high quality software +- respectful, honest, technical-based interaction +- faithful implementation of standards +- security as a mandatory feature A non-official The Apache Way website is available.

diff --git a/content/pages/contact.md b/content/pages/contact.md index 1fe6285c4..75114b8f9 100644 --- a/content/pages/contact.md +++ b/content/pages/contact.md @@ -13,10 +13,10 @@ The source for this website is at Contacting Infra if you are reporting a security issue specific to an ASF project or a project's product. - - `root@apache.org` is an unarchived alias that goes to Infra staff for material that doesn't fit other lists. Please review [Infra policy on sharing sensitive information](sensitive_info.html). +- `users@infra.apache.org` is for general infrastructure discussions and suggestions, and for questions related to ASF infrastructure and the Infra team that do **not** rise to the level of a Jira ticket; so if your question requires guidance or action by Infra, please open a Jira ticket. See the `security@infra` note below if your problem relates to your ASF account in a way that prevents you from opening a Jira ticket. Only committers and ASF members can subscribe to the list. +- `private@infra.apache.org` is for communications that may involve PII, personnel issues, or other information that should not be widely shared. Only ASF Members and Board Members can subscribe to the list. +- Use `security@infra.apache.org` to report **infrastructure-related** security issues (you cannot subscribe to this list) or if your problem prevents you from opening a Jira ticket. See the third entry on Contacting Infra if you are reporting a security issue specific to an ASF project or a project's product. +- `root@apache.org` is an unarchived alias that goes to Infra staff for material that doesn't fit other lists. Please review [Infra policy on sharing sensitive information](sensitive_info.html). In the past there was the `infrastructure@apache.org` mailing list. This address is no longer in use. diff --git a/content/pages/content-moderation.md b/content/pages/content-moderation.md index 0722d8393..fb92b3d13 100644 --- a/content/pages/content-moderation.md +++ b/content/pages/content-moderation.md @@ -44,8 +44,8 @@ If you are a **mailing list moderator**, see this this guidance on possible spam. - - If you still have an issue, report it to `users@infra.apache.org`. +- Review this guidance on possible spam. +- If you still have an issue, report it to `users@infra.apache.org`. If you seem to be receiving spam from an ASF email account, report the issue to `abuse@infra.apache.org`. diff --git a/content/pages/contrib-email-tips.md b/content/pages/contrib-email-tips.md index a3fd4e80d..77a4594a8 100644 --- a/content/pages/contrib-email-tips.md +++ b/content/pages/contrib-email-tips.md @@ -5,10 +5,10 @@ This is a collection of tips for people wishing to contribute to any Public Forum Archive Policy. - - Send your comments to the appropriate mailing list. Well-directed conversations are more productive and easier to find later. See the Contact Apache FAQ. - - Become familiar with the mailing lists. As you browse and search, you will see the way other people do things. Follow the leading examples. - - Consult the archives to see what's been done earlier. - - Do not cross-post messages. In other words, pick a mailing list and send your messages to that mailing list only, not to multiple mailing lists. People may be subscribed to one list and not to the other. Therefore, some people will only see part of the conversation, and some responses will appear on one list and others on another list. +- Send your comments to the appropriate mailing list. Well-directed conversations are more productive and easier to find later. See the Contact Apache FAQ. +- Become familiar with the mailing lists. As you browse and search, you will see the way other people do things. Follow the leading examples. +- Consult the archives to see what's been done earlier. +- Do not cross-post messages. In other words, pick a mailing list and send your messages to that mailing list only, not to multiple mailing lists. People may be subscribed to one list and not to the other. Therefore, some people will only see part of the conversation, and some responses will appear on one list and others on another list.

Do not send HTML

@@ -18,33 +18,33 @@ Note that many modern systems, like GMail, are good about sending plain-text ver

Be respectful of other list participants

- - All participants in Apache lists are expected to abide by our published Code of Conduct. Respectful and considerate communities are one of the pillars of the Apache way. Please aim to provide constructive comments and do not +- All participants in Apache lists are expected to abide by our published Code of Conduct. Respectful and considerate communities are one of the pillars of the Apache way. Please aim to provide constructive comments and do not denigrate others. - - Do not engage in personal attacks. That is not our way. If ever you see one happening, then either help to defuse it or don't comment and let the conversation die. - - Try not to use the word "you". People get defensive when they think that comments are directed at them personally. Consider using "one" or "we" or even "me". Also stay away from "you said" then paraphrasing - too easy to misinterpret another person's words. Try "from what I think I read", "AFAICT" ("as far as I can tell"), and similar phrases to reduce the possibility of confrontation or misunderstanding. - - Direct your comments to the list in general, rather than to any specific person, unless it is something like "@PersonName, your explanation really helped me solve my problem." - - Avoid the use of gender-specific terms like "he" or "she". To avoid "he or she", it is fine to use "they" to refer to a single person. +- Do not engage in personal attacks. That is not our way. If ever you see one happening, then either help to defuse it or don't comment and let the conversation die. +- Try not to use the word "you". People get defensive when they think that comments are directed at them personally. Consider using "one" or "we" or even "me". Also stay away from "you said" then paraphrasing - too easy to misinterpret another person's words. Try "from what I think I read", "AFAICT" ("as far as I can tell"), and similar phrases to reduce the possibility of confrontation or misunderstanding. +- Direct your comments to the list in general, rather than to any specific person, unless it is something like "@PersonName, your explanation really helped me solve my problem." +- Avoid the use of gender-specific terms like "he" or "she". To avoid "he or she", it is fine to use "they" to refer to a single person.

How to write useful questions

- - Research your topic before beginning to discuss a new issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, become informed so you can either a) avoid asking a question altogether or b) provide a useful comment or question. - - Take the time to clearly explain your issue and write a concise email message. Less confusion in the writing facilitates a faster and better response. Everyone will benefit from the extra time on your part. The less unnecessary discussion, the better. - - Every contribution is worthwhile. Even if the ensuing discussion proves it to be off-beam, it may jog ideas for other people. - - Use sensible and concise email Subject: headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a short, descriptive title. - - Keep each topic focused. If some new topic arises then start a new discussion. This leaves the original topic to continue un-cluttered. +- Research your topic before beginning to discuss a new issue. Search and browse through the email archives - your issue may have been discussed before. Do not just perceive a problem and then rush out with a question - instead, become informed so you can either a) avoid asking a question altogether or b) provide a useful comment or question. +- Take the time to clearly explain your issue and write a concise email message. Less confusion in the writing facilitates a faster and better response. Everyone will benefit from the extra time on your part. The less unnecessary discussion, the better. +- Every contribution is worthwhile. Even if the ensuing discussion proves it to be off-beam, it may jog ideas for other people. +- Use sensible and concise email Subject: headings. Search engines, and humans trying to browse a voluminous list, will respond favourably to a short, descriptive title. +- Keep each topic focused. If some new topic arises then start a new discussion. This leaves the original topic to continue un-cluttered.

Practice patience

- - Most people participate in Apache projects on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond +- Most people participate in Apache projects on a volunteer basis and in their "spare time". These enthusiasts will attempt to respond to issues, but it may take a little while to get your answers. - - Most list participants are very busy. Their replies might appear to be curt when they direct you to a document, or give a short answer without niceties. If they spent too long preparing each reply, then they would become exhausted. - - Do not send development or use questions in private emails. Keep the discussion on the mailing list, where we can all learn and assist each other. +- Most list participants are very busy. Their replies might appear to be curt when they direct you to a document, or give a short answer without niceties. If they spent too long preparing each reply, then they would become exhausted. +- Do not send development or use questions in private emails. Keep the discussion on the mailing list, where we can all learn and assist each other.

Sitemap for Apache email information

- - Listing of ASF Mailing Lists - - Code of Conduct - - Public Forum Archive Policy - - Additional tips from the Apache Cocoon community - - How to ask Questions the Smart Way - - RFC 1855: Netiquette Guidelines (text document) +- Listing of ASF Mailing Lists +- Code of Conduct +- Public Forum Archive Policy +- Additional tips from the Apache Cocoon community +- How to ask Questions the Smart Way +- RFC 1855: Netiquette Guidelines (text document) diff --git a/content/pages/contributors.md b/content/pages/contributors.md index 324dc1aa8..d39cb3955 100644 --- a/content/pages/contributors.md +++ b/content/pages/contributors.md @@ -9,11 +9,11 @@ More information is available in the [guide](new-committers-guide.html) and [FAQ - - Community Development is here to help! - - Everything happens on mailing lists - - How open-source works at Apache - - Source code repositories - - Providing feedback to Apache projects

+- Community Development is here to help! +- Everything happens on mailing lists +- How open-source works at Apache +- Source code repositories +- Providing feedback to Apache projects

Community Development is here to help!

@@ -27,19 +27,19 @@ Virtually everything at Apache happens on one of our publicly archived mailing l There are many books, presentations, and academic papers about the way open-source software development works and how you can become a valuable member of the open source/free software community. For an overview of how it works at Apache, see - - the ASF home page - - the ASF How it works document - - Cameron Riley's [Understanding Opensource](understanding-opensource.html) document - - the Free Software Foundation (FSF) website - - the Open Source Initiative website - - The Cathedral and the Bazaar +- the ASF home page +- the ASF How it works document +- Cameron Riley's [Understanding Opensource](understanding-opensource.html) document +- the Free Software Foundation (FSF) website +- the Open Source Initiative website +- The Cathedral and the Bazaar

Source code repositories

Apache projects use either of these repository systems: - - [Subversion](svn-basics.html) - - [Git](git-primer.html). +- [Subversion](svn-basics.html) +- [Git](git-primer.html).

Nightly code / Development code

diff --git a/content/pages/crypto.md b/content/pages/crypto.md index 3147c289b..83b5fb5c0 100644 --- a/content/pages/crypto.md +++ b/content/pages/crypto.md @@ -15,8 +15,8 @@ Notices of updates to this page appear on the Contents - - Overview - - Frequently Asked Questions +- Overview +- Frequently Asked Questions

Overview

@@ -24,22 +24,22 @@ The U.S. Government places Check the Export Control Classification Number (ECCN). - - Update the exports page with source links. - - Notify the U.S. Government of the new code. - - Inform users. +- Check the Export Control Classification Number (ECCN). +- Update the exports page with source links. +- Notify the U.S. Government of the new code. +- Inform users.

Check the Export Control Classification Number (ECCN)

Section 742.15(b) of the Export Administration Regulations (EAR) authorizes exports and reexports, without review, of encryption source and object code provided the following conditions are met: - - the encryption source code is controlled by ECCN 5D002. - - the encryption source code will be publicly available (published and made available to the public without restrictions upon its further dissemination). - - a notification is sent to the U.S. Government's Bureau of Industry and Security (BIS) and the ENC Encryption Request Coordinator at or before making the code publicly available. Current ASF processes satisfy the "publicly available" requirement. The notification requirement is described below. However, it is important to ensure the included cryptographic functionality meets the definition of ECCN D002, which can be summarized as: - - Software specially designed or modified for the development, production or use of any of the other software of this list, or software designed to certify other software on this list; or - - Software using a "symmetric algorithm" employing a key length in excess of 56-bits; or - - Software using an "asymmetric algorithm" where the security of the algorithm is based on: factorization of integers in excess of 512 bits (e.g., RSA), computation of discrete logarithms in a multiplicative group of a finite field of size greater than 512 bits (e.g., Diffie-Hellman over Z/pZ), or other discrete logarithms in a group in excess of 112 bits (e.g., Diffie-Hellman over an elliptic curve). - - Software designed or modified to perform cryptanalytic functions If the cryptographic functionality is limited to one of the above definitions, it should be classified as ECCN 5D002, and the remaining two steps should be taken (described below). If the release may contain cryptographic functionality beyond what is described above, please contact +- the encryption source code is controlled by ECCN 5D002. +- the encryption source code will be publicly available (published and made available to the public without restrictions upon its further dissemination). +- a notification is sent to the U.S. Government's Bureau of Industry and Security (BIS) and the ENC Encryption Request Coordinator at or before making the code publicly available. Current ASF processes satisfy the "publicly available" requirement. The notification requirement is described below. However, it is important to ensure the included cryptographic functionality meets the definition of ECCN D002, which can be summarized as: + - Software specially designed or modified for the development, production or use of any of the other software of this list, or software designed to certify other software on this list; or + - Software using a "symmetric algorithm" employing a key length in excess of 56-bits; or + - Software using an "asymmetric algorithm" where the security of the algorithm is based on: factorization of integers in excess of 512 bits (e.g., RSA), computation of discrete logarithms in a multiplicative group of a finite field of size greater than 512 bits (e.g., Diffie-Hellman over Z/pZ), or other discrete logarithms in a group in excess of 112 bits (e.g., Diffie-Hellman over an elliptic curve). + - Software designed or modified to perform cryptanalytic functions If the cryptographic functionality is limited to one of the above definitions, it should be classified as ECCN 5D002, and the remaining two steps should be taken (described below). If the release may contain cryptographic functionality beyond what is described above, please contact the ASF Vice President for Legal Affairs.

Update the Exports Page with Source Links

diff --git a/content/pages/csp.md b/content/pages/csp.md index 2e4e43280..5fe18bf97 100644 --- a/content/pages/csp.md +++ b/content/pages/csp.md @@ -5,9 +5,9 @@ This policy became effective **March 1, 2025**. For your project's website: - - External trackers from 3rd party providers are **not allowed**. The ASF offers Matomo analytics for all project websites through analytics.apache.org. - - External resources, such as videos or PDFs, from providers with which we do not have a Data Processing Agreement (DPA) are **not allowed** to be embedded in the project's website. If you have a DPA request or inquiry, contact `privacy@apache.org`. They can also tell you if a provider whose content you want to embed in your website has already signed a DPA. - - Links that lead to downloadable external resources **are allowed** if the site visitor must give explicit consent in order to see or use the content (such as by clicking a button or a link). This consent cannot be opt-out, and there must be a clear way for the visitor to retract consent at a later time. +- External trackers from 3rd party providers are **not allowed**. The ASF offers Matomo analytics for all project websites through analytics.apache.org. +- External resources, such as videos or PDFs, from providers with which we do not have a Data Processing Agreement (DPA) are **not allowed** to be embedded in the project's website. If you have a DPA request or inquiry, contact `privacy@apache.org`. They can also tell you if a provider whose content you want to embed in your website has already signed a DPA. +- Links that lead to downloadable external resources **are allowed** if the site visitor must give explicit consent in order to see or use the content (such as by clicking a button or a link). This consent cannot be opt-out, and there must be a clear way for the visitor to retract consent at a later time. This policy brings project websites into alignment with the security and privacy parameters defined by the VP, Data Privacy and as requested by The ASF Security Committee. We ask that projects do not circumvent them without express permission from our VP, Data Privacy. diff --git a/content/pages/cwiki.md b/content/pages/cwiki.md index 69b0b20a0..afc15808a 100644 --- a/content/pages/cwiki.md +++ b/content/pages/cwiki.md @@ -1,11 +1,11 @@ Title: Confluence Wiki space for your project license: https://www.apache.org/licenses/LICENSE-2.0 - - Overview - - Getting your project cwiki space - - Managing your cwiki space - - Watching a cwiki page - - FAQs +- Overview +- Getting your project cwiki space +- Managing your cwiki space +- Watching a cwiki page +- FAQs

Overview

Every Apache Software Foundation project can establish, manage, and populate a space on the Confluence Wiki (cwiki) that Infra maintains for the ASF. Projects can use this space to share and store important information, code snippets, and project procedures. Some projects also use their wiki space to provide product documentation for end users. @@ -17,34 +17,34 @@ Many thanks to Atlassian Sof

Getting your project cwiki space

Your ASF Project PMC can request creation of a new space. - - On the Self-Service portal select _Create a new Confluence space_. - - Include the cwiki account name of a PMC member (preferably the PMC chair) who will help administer the space. - - Specify the key name for the space. The key name cannot be changed. If you use Jira, you might want to use the same key name. +- On the Self-Service portal select _Create a new Confluence space_. +- Include the cwiki account name of a PMC member (preferably the PMC chair) who will help administer the space. +- Specify the key name for the space. The key name cannot be changed. If you use Jira, you might want to use the same key name. When Infra creates the space, it sets up a $project-committer group (or equivalent) with full rights to the project's space.

Managing your cwiki space

- - Each project community manages its own cwiki space and can decide how best to arrange and populate its pages. - - Your cwiki space has a permissions feature that lets you set access levels for various areas of the space or its individual pages. If your project is using part of the space for end-user documentation, it can leave that section without access restrictions, while restricting access to other areas to project committers. - - Editing access to your project's space is restricted to Project committers and individuals who have filed a Contributor's License Agreement with the ASF. - - You can create user groups in addition to the standard groups: +- Each project community manages its own cwiki space and can decide how best to arrange and populate its pages. +- Your cwiki space has a permissions feature that lets you set access levels for various areas of the space or its individual pages. If your project is using part of the space for end-user documentation, it can leave that section without access restrictions, while restricting access to other areas to project committers. +- Editing access to your project's space is restricted to Project committers and individuals who have filed a Contributor's License Agreement with the ASF. +- You can create user groups in addition to the standard groups:

Watching a cwiki page

Cwiki users, including those not involved in a project, can 'watch' pages in a project's space to receive update notices when information on that page changes. To watch a page: - - Log in in to the ASF cwiki. - - Locate the page you want to watch. - - Click **Watch** on the top menu bar. +- Log in in to the ASF cwiki. +- Locate the page you want to watch. +- Click **Watch** on the top menu bar. To stop watching a page: - - Log in in to the ASF cwiki. - - Click your profile icon at the top right of the wiki page. - - From the dropdown menu that appears, select **Watches**. - - The list of pages you are watching appears, and you can remove those you no longer want to watch. +- Log in in to the ASF cwiki. +- Click your profile icon at the top right of the wiki page. +- From the dropdown menu that appears, select **Watches**. +- The list of pages you are watching appears, and you can remove those you no longer want to watch. Infra can help you set up a role account that can watch for any changes in your space and send notices about them to an email list. This can lead to a large amount of traffic, so you can choose a digest option that provides a daily summary of changes. diff --git a/content/pages/dependabot.md b/content/pages/dependabot.md index 4b5e03d0c..ac74c01c5 100644 --- a/content/pages/dependabot.md +++ b/content/pages/dependabot.md @@ -268,6 +268,6 @@ updates:

Further reading

- - Configuring Dependabot version updates - - Configuration options for the dependabot.yml file - - [GitHub Actions Policy](github-actions-policy.html) (Dependabot is **required** for the `github-actions` ecosystem) +- Configuring Dependabot version updates +- Configuration options for the dependabot.yml file +- [GitHub Actions Policy](github-actions-policy.html) (Dependabot is **required** for the `github-actions` ecosystem) diff --git a/content/pages/digicert-access.md b/content/pages/digicert-access.md index b482c4a66..991b61a95 100644 --- a/content/pages/digicert-access.md +++ b/content/pages/digicert-access.md @@ -5,10 +5,10 @@ The DigiCert code signin To gain access to the service, create a Jira ticket with the following information: - - Set the component to `code signing` - - The name of the PMC requesting the code signing service - - The Apache IDs of the committer(s) who will act as release managers - - The Apache IDs of any additional PMC members who require access to monitor the service +- Set the component to `code signing` +- The name of the PMC requesting the code signing service +- The Apache IDs of the committer(s) who will act as release managers +- The Apache IDs of any additional PMC members who require access to monitor the service The infra team will then request the account creation and (after a few e-mails and configuring a OTP token) you will have an account that lets you access the web GUI. Each PMC member must have their own account to access the web GUI. diff --git a/content/pages/email_lists.md b/content/pages/email_lists.md index 1bdec22a5..af3203227 100644 --- a/content/pages/email_lists.md +++ b/content/pages/email_lists.md @@ -3,36 +3,36 @@ license: https://www.apache.org/licenses/LICENSE-2.0 In `lists.apache.org` you can browse, search for, and read emails on mailing lists of The ASF. - - Without logging in, you can access email in public ASF mailing lists. - - If you have logged in: - - if you are an ASF Member, you can access all ASF mailing lists. - - if you are not an ASF Member but are on the PMC of a project, you can access, in addition to the public lists, the private lists of that project. +- Without logging in, you can access email in public ASF mailing lists. +- If you have logged in: + - if you are an ASF Member, you can access all ASF mailing lists. + - if you are not an ASF Member but are on the PMC of a project, you can access, in addition to the public lists, the private lists of that project. If you have logged in, and depending on your status as noted above, you can respond to email threads and create new messages in the email list you are currently viewing. The user interface does not have controls for these actions; instead, there are shortcut keys: - - `H`: Display the help window. - - `C`: Start a new email thread in the current list. - - `R`: Reply to the current email thread. - - `S`: Go to the search bar. - - `Escape`: Hide modal dialogues or collapse the current thread. - - In list view: - - `right arrow`: Move down the current list to display the next-older bunch of emails. - - `left arrow`: Move up the current list to display the next-newer bunch of emails. +- `H`: Display the help window. +- `C`: Start a new email thread in the current list. +- `R`: Reply to the current email thread. +- `S`: Go to the search bar. +- `Escape`: Hide modal dialogues or collapse the current thread. +- In list view: + - `right arrow`: Move down the current list to display the next-older bunch of emails. + - `left arrow`: Move up the current list to display the next-newer bunch of emails. ## Searching To display your search options, click the down-arrow at the right of the `search` field. - - Opt to search in - - the current list - - all the lists of this domain; that is, if you are looking at any Apache Royale list, you can search at the same time all the email lists of `royale.apache.org` to which you have access. - - all The ASF's email lists to which you have access. - - You can restrict the search to - - a specific date range - - the author of the email - - a keyword in the title of the email - - the recipient of the email (a group or individual) - - a keyword within the body of the email +- Opt to search in + - the current list + - all the lists of this domain; that is, if you are looking at any Apache Royale list, you can search at the same time all the email lists of `royale.apache.org` to which you have access. + - all The ASF's email lists to which you have access. +- You can restrict the search to + - a specific date range + - the author of the email + - a keyword in the title of the email + - the recipient of the email (a group or individual) + - a keyword within the body of the email ## If the email you sent does not appear diff --git a/content/pages/gfm.md b/content/pages/gfm.md index aa2450c13..dcb37f5c7 100644 --- a/content/pages/gfm.md +++ b/content/pages/gfm.md @@ -58,11 +58,11 @@ SEE INSTEAD: [Trademark Resources Site Map][resources]. If you are moving a project site of the Apache CMS and will be using the ASF-Pelican template: - - Change any **mdtext** file extension to **md**. - - Replace the multiple line `notice:` at the top of the file with a one-line reference to the Apache License. - - Any {#id} and {.class} annotations have any # tags between the annotation and the heading text removed. - - Only one {#id} or {.class} annotation is allowed on a tag. - - {.class} annotations are seldom used. +- Change any **mdtext** file extension to **md**. +- Replace the multiple line `notice:` at the top of the file with a one-line reference to the Apache License. +- Any {#id} and {.class} annotations have any # tags between the annotation and the heading text removed. +- Only one {#id} or {.class} annotation is allowed on a tag. +- {.class} annotations are seldom used. [1]: https://github.com/github/cmark-gfm [2]: https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/ diff --git a/content/pages/git-primer.md b/content/pages/git-primer.md index e122ee560..dd223a294 100644 --- a/content/pages/git-primer.md +++ b/content/pages/git-primer.md @@ -5,15 +5,15 @@ This document is a primer on using Git for an Apache Software Foundation project ## Contents - - Repository types - - Public and private repositories - - Repository checkout - - Using .asf.yaml - - Committers: getting started - - Windows users - - Line endings - - Troubleshooting - - Further reading +- Repository types + - Public and private repositories +- Repository checkout +- Using .asf.yaml +- Committers: getting started +- Windows users +- Line endings +- Troubleshooting +- Further reading

Repository types

@@ -30,9 +30,9 @@ Projects can set up as many **public repositories** as their development work re Each project can also have a **private repository** space for working on sensitive issues such as: - - security patches - - writing a draft of the project Board report when there is a section that will appear in a `` tag - - sharing credentials +- security patches +- writing a draft of the project Board report when there is a section that will appear in a `` tag +- sharing credentials The private repository is **not** for uses such as project code development not related to a security issue. @@ -52,17 +52,17 @@ https://gitbox.apache.org/repos/asf/reponame.git ### Cloning a repository - - **Committers**: `$ git clone https://gitbox.apache.org/repos/asf/reponame.git` - - **Non-Committers**: `$ git clone http://gitbox.apache.org/repos/asf/reponame.git` +- **Committers**: `$ git clone https://gitbox.apache.org/repos/asf/reponame.git` +- **Non-Committers**: `$ git clone http://gitbox.apache.org/repos/asf/reponame.git`

Using .asf.yaml

`.asf.yaml` is a branch-specific YAML configuration file that a project may create (using a text editor of your choice) and put in the root of a Git repository to control features such as - - notification schemes - - website staging - - GitHub settings - - Pelican builds +- notification schemes +- website staging +- GitHub settings +- Pelican builds For details on how .asf.yaml can help you manage your GitHub settings, see github.com/apache/infrastructure-asfyaml/edit/main/README.md. @@ -124,8 +124,8 @@ Instead of setting up a `~/.netrc` file you need to: In general, you should normalize line endings in the Git repository and set them to be platform specific on checkout. - - The `msysgit` installer on **Windows** will prompt you to set the `core.autocrlf` setting to `true` by default. - - On **Mac OS X or Linux**, use this setting: `$ git config --global core.autocrlf input` +- The `msysgit` installer on **Windows** will prompt you to set the `core.autocrlf` setting to `true` by default. +- On **Mac OS X or Linux**, use this setting: `$ git config --global core.autocrlf input` Further details and attributes for handling line endings differently per file type are available at Configuring Git to handle line endings. @@ -148,9 +148,9 @@ $ git config remote.origin.url https://gitbox.apache.org/repos/asf/reponame.git

Further reading

- - [GitHub Actions Policy](github-actions-policy.html) - - [GitHub Apps](github-apps.html) - - [GitHub Pages](github-pages.html) - - [GitHub roles](github-roles.html) - - GitHub Learning Lab - - Git Cheat Sheets +- [GitHub Actions Policy](github-actions-policy.html) +- [GitHub Apps](github-apps.html) +- [GitHub Pages](github-pages.html) +- [GitHub roles](github-roles.html) +- GitHub Learning Lab +- Git Cheat Sheets diff --git a/content/pages/git.md b/content/pages/git.md index 147041e60..a5f886c79 100644 --- a/content/pages/git.md +++ b/content/pages/git.md @@ -12,9 +12,9 @@ mirrors are also available on GitHub. Please file an INFRA ticket (component: Git) to request a new codebase to be mirrored or to change the settings of an existing mirror. When requesting a new mirror, please include the following information: - - Name of the codebase, for example "Apache Tika" - - Name of the requested Git mirror, for example "tika.git" - - Subversion path of the codebase, for example "/lucene/tika" +- Name of the codebase, for example "Apache Tika" +- Name of the requested Git mirror, for example "tika.git" +- Subversion path of the codebase, for example "/lucene/tika" = Subversion layout, in case it is different from the standard "trunk, branches, tags" structure.

Workflow

diff --git a/content/pages/github-actions-policy.md b/content/pages/github-actions-policy.md index 5607f57fe..3ce01f8ab 100644 --- a/content/pages/github-actions-policy.md +++ b/content/pages/github-actions-policy.md @@ -20,10 +20,10 @@ See the [Dependabot](dependabot.html) page for how to configure it, including [g Due to misconfigurations in their builds, some projects have been using unsupportable numbers of [GitHub Actions](github-actions-secrets.html). As part of fixing this situation, Infra has established a policy for GitHub Actions use: - - All workflows **MUST** have a job concurrency level less than or equal to 20. This means a workflow cannot have more than 20 jobs running at the same time across all matrices. - - All workflows **SHOULD** have a job concurrency level less than or equal to 15. Just because 20 is the max, doesn't mean you should strive for 20. - - The average number of minutes a project uses _per calendar week_ **MUST NOT** exceed the equivalent of 25 full-time runners (250,000 minutes, or 4,200 hours). - - The average number of minutes a project uses _in any consecutive five-day period_ **MUST NOT** exceed the equivalent of 30 full-time runners (216,000 minutes, or 3,600 hours). +* All workflows **MUST** have a job concurrency level less than or equal to 20. This means a workflow cannot have more than 20 jobs running at the same time across all matrices. +* All workflows **SHOULD** have a job concurrency level less than or equal to 15. Just because 20 is the max, doesn't mean you should strive for 20. +* The average number of minutes a project uses _per calendar week_ **MUST NOT** exceed the equivalent of 25 full-time runners (250,000 minutes, or 4,200 hours). +* The average number of minutes a project uses _in any consecutive five-day period_ **MUST NOT** exceed the equivalent of 30 full-time runners (216,000 minutes, or 3,600 hours). Projects whose builds consistently cross the maximum use limits will lose their access to GitHub Actions until they fix their build configurations. diff --git a/content/pages/github-actions-secrets.md b/content/pages/github-actions-secrets.md index 88d4041f0..14575a3a5 100644 --- a/content/pages/github-actions-secrets.md +++ b/content/pages/github-actions-secrets.md @@ -11,7 +11,7 @@ The ASF maxes out its runner allocation quite often, so a project needs to plan **Evolving knowledge** -- If you are considering using GitHub Actions with buildsy, please subscribe to the `builds@ a.o` mailing list, where there is a continuing discussion on this topic and others related to continuous integration development. +- If you are considering using GitHub Actions with buildsy, please subscribe to the `builds@ a.o` mailing list, where there is a continuing discussion on this topic and others related to continuous integration development. - The community is curating a Wiki page about the current state of using GitHub Actions for ASF projects. @@ -55,12 +55,12 @@ To extend the validity of the token, adjust the `develocity-token-expiry` action Further information is at these pages: - - Managing Develocity access keys - - Short-lived access tokens +- Managing Develocity access keys +- Short-lived access tokens ### Links ### - - The [Apache GitHub Actions Policy](github-actions-policy.html) - - Advice for GitHub Actions Security - - [GitHub Actions](services.html#github-actions) on the Services and Tools page, on shared runner queues and how to reduce your project's load - - [Dependabot](dependabot.html) for dependency management, which is **required** for the `github-actions` ecosystem +- The [Apache GitHub Actions Policy](github-actions-policy.html) +- Advice for GitHub Actions Security +- [GitHub Actions](services.html#github-actions) on the Services and Tools page, on shared runner queues and how to reduce your project's load +- [Dependabot](dependabot.html) for dependency management, which is **required** for the `github-actions` ecosystem diff --git a/content/pages/github-pages.md b/content/pages/github-pages.md index ae93a45f3..4f0eaa53c 100644 --- a/content/pages/github-pages.md +++ b/content/pages/github-pages.md @@ -11,9 +11,9 @@ See .asf.yaml. - - Use Buildbot in combination with Jekyll and Pelican - - Use your own build tool in combination with gh-pages or .asf.yaml +- Use Infra's .asf.yaml. +- Use Buildbot in combination with Jekyll and Pelican +- Use your own build tool in combination with gh-pages or .asf.yaml ### Using gh-pages for the project website diff --git a/content/pages/github-roles.md b/content/pages/github-roles.md index f31c47d83..627d448a9 100644 --- a/content/pages/github-roles.md +++ b/content/pages/github-roles.md @@ -3,9 +3,9 @@ license: https://www.apache.org/licenses/LICENSE-2.0 Projects can assign roles to people who want access to the project GitHub repositories. Each role gives a different level of access. For Apache projects, the available roles are: - - Read: View or discuss the project code or documentation - - Triage (see below): Manage issues and pull requests without having write access - - Write: For contributors who actively push code updates to the repository +- Read: View or discuss the project code or documentation +- Triage (see below): Manage issues and pull requests without having write access +- Write: For contributors who actively push code updates to the repository See Managing access to your organization's repositories'. @@ -15,11 +15,11 @@ As of September, 2020 Apache projects can assign the GitHub _triage_ role to PMC A person with the triage role can - - apply labels to code - - close, reopen, and assign issues and pull requests - - apply milestones - - mark duplicate issues and pull requests - - request pull-request reviews +- apply labels to code +- close, reopen, and assign issues and pull requests +- apply milestones +- mark duplicate issues and pull requests +- request pull-request reviews Git recommends the role "for contributors who need to proactively manage issues and pull requests without write access." It is a good role for people who are interested in supporting and contributing to the project, but who are not ready to be Committers. diff --git a/content/pages/glossary.md b/content/pages/glossary.md index bbcac32e0..a20e53f8f 100644 --- a/content/pages/glossary.md +++ b/content/pages/glossary.md @@ -3,10 +3,10 @@ license: https://www.apache.org/licenses/LICENSE-2.0 _This page will hold definitions of frequently-used technical terms._ - - **checksum** - definition coming - - **CTR** - "commit, then review" - explanation coming - - **hashtag** (or 'hash') - definition coming - - **lint checking** - definition coming - - **rebase** - Actions to keep the code your branch in sync with the code in the trunk or release branch. - - **RTC** - "review, then commit" - explanation coming - - **signature** - definition coming +- **checksum** - definition coming +- **CTR** - "commit, then review" - explanation coming +- **hashtag** (or 'hash') - definition coming +- **lint checking** - definition coming +- **rebase** - Actions to keep the code your branch in sync with the code in the trunk or release branch. +- **RTC** - "review, then commit" - explanation coming +- **signature** - definition coming diff --git a/content/pages/hosting-external-agent.md b/content/pages/hosting-external-agent.md index 49724f436..fcf8bc3ec 100644 --- a/content/pages/hosting-external-agent.md +++ b/content/pages/hosting-external-agent.md @@ -5,22 +5,22 @@ Individuals and organizations can support the work of the ASF and its projects b **Notes** - - Ubuntu is a core supported OS at the ASF and we do not need any external hosting by individuals at this time. - - Organizations wanting to donate multiple VMs for Jenkins and/or Buildbot use should email `private@infra.apache.org` to start discussions. +- Ubuntu is a core supported OS at the ASF and we do not need any external hosting by individuals at this time. +- Organizations wanting to donate multiple VMs for Jenkins and/or Buildbot use should email `private@infra.apache.org` to start discussions. ## Getting ready to host ### There are a few things you'll need to know and to adhere to. - - Keep up to date with security patches etc,, the obvious stuff; we may want to be added to root alias for security reporting etc. - - Spec requirements: - - minimum 16GB RAM - - 500GB Hard disk - - A permanent static IP address - - You must be an ASF Committer. - - You must subscribe to the `builds@a.o` email list. - - Maintain and provide a link to a public page that lists software you add to your agent. - - Open an INFRA Jira ticket so we can complete your hosting set up when you are completely ready. +- Keep up to date with security patches etc,, the obvious stuff; we may want to be added to root alias for security reporting etc. +- Spec requirements: + - minimum 16GB RAM + - 500GB Hard disk + - A permanent static IP address +- You must be an ASF Committer. +- You must subscribe to the `builds@a.o` email list. +- Maintain and provide a link to a public page that lists software you add to your agent. +- Open an INFRA Jira ticket so we can complete your hosting set up when you are completely ready. ### For Buildbot ### @@ -30,5 +30,5 @@ When you are ready, liaise with `root@a.o` to negotiate connection credentials. ### For Jenkins ### - - Create a Jenkins user and group using /home/jenkins. - - Add the Jenkins ssh public key into the users' `~/.ssh/authorized` keys. +- Create a Jenkins user and group using /home/jenkins. +- Add the Jenkins ssh public key into the users' `~/.ssh/authorized` keys. diff --git a/content/pages/how-to-mirror.md b/content/pages/how-to-mirror.md index 544c5b68a..43bd4a2ce 100644 --- a/content/pages/how-to-mirror.md +++ b/content/pages/how-to-mirror.md @@ -7,25 +7,25 @@ Organizations may wish to create a download mirror that includes the releases of Here is how to set up such a mirror. - - Requirements - - Mirroring techniques - - Mirror host information - - Testing your mirror - - Verifying a download - - Questions? +- Requirements +- Mirroring techniques +- Mirror host information +- Testing your mirror +- Verifying a download +- Questions?

Requirements

Hosting a mirror has a few requirements: - - You should have at least 150 GB of available disk space. The current distribution directory is around 110 GB, but it is constantly expanding. - - You should not trim or abridge the mirrored tree in any way. - - You should not modify the mirrored tree in any way. In particular, you should not alter or remove HEADER.html or README.html files. See below for adding information about the mirror host. +- You should have at least 150 GB of available disk space. The current distribution directory is around 110 GB, but it is constantly expanding. +- You should not trim or abridge the mirrored tree in any way. +- You should not modify the mirrored tree in any way. In particular, you should not alter or remove HEADER.html or README.html files. See below for adding information about the mirror host. We encourage you to - - do an **update-check** at least four times a day a day. You may sync a maximum of six times per day, but only if you have a slow or poor connection that causes timeouts. - - run the Apache HTTP Server version 2.2 or later and use the following configuration for your web mirror to allow all the features of our download site to function optimally: +- do an **update-check** at least four times a day a day. You may sync a maximum of six times per day, but only if you have a slow or poor connection that causes timeouts. +- run the Apache HTTP Server version 2.2 or later and use the following configuration for your web mirror to allow all the features of our download site to function optimally: ``` @@ -54,9 +54,9 @@ Update your mirror with: rsync -avz --delete --safe-links rsync.apache.org::apache-dist /path/to/mirror ``` - - Don't rsync "on the hour" (`cronjob minute 0`). Pick a random minute between 5 and 55. Never run cronjobs at minute 0 unless the nature of the job requires it. - - Run the job four times a day; no more than six times a day in any case. - - Check the output from the rsync job regularly so you can detect problems like lack of disk space or permission issues. +- Don't rsync "on the hour" (`cronjob minute 0`). Pick a random minute between 5 and 55. Never run cronjobs at minute 0 unless the nature of the job requires it. +- Run the job four times a day; no more than six times a day in any case. +- Check the output from the rsync job regularly so you can detect problems like lack of disk space or permission issues. ### Excluding resource-intensive projects @@ -93,8 +93,8 @@ Here is how to add information explaining who is hosting the private download mi The contents of README.html appear near the bottom of your mirror's home page. - - Only customize the home-page (top-level) README.html. Do not change any other README.html files. - - Don't omit the '/' in `"/README.html"`. +- Only customize the home-page (top-level) README.html. Do not change any other README.html files. +- Don't omit the '/' in `"/README.html"`. Please limit the contents of the README.html to something like: @@ -108,10 +108,10 @@ Search engines interpret referring to specific services or products as _PageRank If your mirror is not working properly, check the following: - - Page headers and footers display correctly. - - All top-level directories and files on the ASF mirror are present on your mirror. - - Download a couple of files to check that the process works. - - Trying to download a missing file should generate a `404 Not Found` error. You can verify this by modifying one of the valid URLs that you tested above. +- Page headers and footers display correctly. +- All top-level directories and files on the ASF mirror are present on your mirror. +- Download a couple of files to check that the process works. +- Trying to download a missing file should generate a `404 Not Found` error. You can verify this by modifying one of the valid URLs that you tested above.

Verifying the download

diff --git a/content/pages/infra-contact.md b/content/pages/infra-contact.md index cc9967037..f0b58e325 100644 --- a/content/pages/infra-contact.md +++ b/content/pages/infra-contact.md @@ -204,13 +204,13 @@ Please review the tables above before filing a ticket - often you or someone in
Before you press `Send` on your ticket:
- - **Ask** in your project whether someone has the karma to implement the requested change. This eases the load on the infra team. The moderators and volunteer admins of the project's issue tracker and wiki can often address issues with those services. - - **Aggregate requests**: instead of sending five emails, each asking for one more moderator to be added, send one email asking for five moderators to be added. - - **CC your PMC** on emails. When creating Jira tickets, some cases **SHOULD** or even **MUST** demonstrate PMC consensus. If the ticket does not demonstrate PMC consensus, Infra will close the ticket as **invalid** or **reject** it. For more details, please refer to our [Jira Guidelines](jira-guidelines.html). - - If you create a Jira ticket, create it in the **right Jira component**. This helps the team spot pending tasks in their areas. If it's not obvious which component is the right one, select "documentation". - - **Be patient**. It may take a few days for someone to respond. - - **Research your topic**. See the developer information section. - - See also [Jira tickets for Infra](jira-for-infra.html). +- **Ask** in your project whether someone has the karma to implement the requested change. This eases the load on the infra team. The moderators and volunteer admins of the project's issue tracker and wiki can often address issues with those services. +- **Aggregate requests**: instead of sending five emails, each asking for one more moderator to be added, send one email asking for five moderators to be added. +- **CC your PMC** on emails. When creating Jira tickets, some cases **SHOULD** or even **MUST** demonstrate PMC consensus. If the ticket does not demonstrate PMC consensus, Infra will close the ticket as **invalid** or **reject** it. For more details, please refer to our [Jira Guidelines](jira-guidelines.html). +- If you create a Jira ticket, create it in the **right Jira component**. This helps the team spot pending tasks in their areas. If it's not obvious which component is the right one, select "documentation". +- **Be patient**. It may take a few days for someone to respond. +- **Research your topic**. See the developer information section. +- See also [Jira tickets for Infra](jira-for-infra.html). **Thanks**. Making requests following these guidelines might require a little effort, but saves time for all involved. diff --git a/content/pages/infra-incubator.md b/content/pages/infra-incubator.md index d8ccc106f..759c8507a 100644 --- a/content/pages/infra-incubator.md +++ b/content/pages/infra-incubator.md @@ -37,9 +37,9 @@ Mailing lists are an integral part of the decision-making process for projects a Typically, a project will need three lists - - private@ for podling PMC communications, including recording formal decisions and discussion of security issues - - dev@ for development discussions - - commits@ for code commit notifications +- private@ for podling PMC communications, including recording formal decisions and discussion of security issues +- dev@ for development discussions +- commits@ for code commit notifications Projects may also request separate lists for issues, pull requests, and users (this is very important once you do your first software release and begin to develop a user community) at any time. diff --git a/content/pages/infra-mail.md b/content/pages/infra-mail.md index 754a13a76..be0c8d14d 100644 --- a/content/pages/infra-mail.md +++ b/content/pages/infra-mail.md @@ -9,13 +9,13 @@ You can subscribe in the normal way. The moderators will verify that you are an

The lists

- - `users@infra`: Infra uses the general discussion list to discuss issues concerning the operation of the Apache Software Foundation systems, and for committers to report problems or issues. This is not the address for questions about +- `users@infra`: Infra uses the general discussion list to discuss issues concerning the operation of the Apache Software Foundation systems, and for committers to report problems or issues. This is not the address for questions about the ASF or any of its projects. It is for communication between ASF committers only to support the infrastructure. Anyone may send mail to report problems with ASF systems, but check the status page before mailing to see whether Infra already knows about what you have noticed. - - `private@infra`: For the core infra@ team only. It focuses on the infrastructure team working directly on pressing issues. Infra moderates subscriptions, which are restricted to ASF members and current infra [volunteers](infra-volunteer.html). Only +- `private@infra`: For the core infra@ team only. It focuses on the infrastructure team working directly on pressing issues. Infra moderates subscriptions, which are restricted to ASF members and current infra [volunteers](infra-volunteer.html). Only subscribers can post. - - `commits@infra`: SVN commit messages for the ASF Infrastructure trunk, and Git commit messages for ASF Infra. - - `issues@infra`: Messages from the INFRA Issue Tracker. Only ASF committers and people invited by the infra@ team can join. To "post" to this list, file a Jira comment which Jira sends to the list. - - `site-cvs@`: Private lists for SVN commit messages for the ASF Infrastructure website. - - `site-dev@`: A list for discussion of every aspect of the small number of websites that are centrally managed by the +- `commits@infra`: SVN commit messages for the ASF Infrastructure trunk, and Git commit messages for ASF Infra. +- `issues@infra`: Messages from the INFRA Issue Tracker. Only ASF committers and people invited by the infra@ team can join. To "post" to this list, file a Jira comment which Jira sends to the list. +- `site-cvs@`: Private lists for SVN commit messages for the ASF Infrastructure website. +- `site-dev@`: A list for discussion of every aspect of the small number of websites that are centrally managed by the ASF (e.g. /dev/) and for co-ordination of infrastructure needs and publishing methods for all ASF project websites. Participation is open to to any committer or interested party invited by a committer (by sending an email to site-dev-owner). The list is normally low volume. - - `infrastructure-dev@`: This list was closed in October, 2016 and not replaced. Instead please use `users@infra`. It was dedicated to developing and documenting software tools for potential ASF infrastructure. +- `infrastructure-dev@`: This list was closed in October, 2016 and not replaced. Instead please use `users@infra`. It was dedicated to developing and documenting software tools for potential ASF infrastructure. diff --git a/content/pages/infra-reports.md b/content/pages/infra-reports.md index 3f0f905a8..808d0f624 100644 --- a/content/pages/infra-reports.md +++ b/content/pages/infra-reports.md @@ -7,15 +7,15 @@ Some of the reports are open to the public, while others are restricted to those ## Reports available to all - - **Uptime Statistics**: This dashboard provides an overview of uptime of a wide range of services, including email, forums and Confluence wikis, version control systems, and websites. - - **Public Download Statistics**: On this screen you can select an ASF project and then review and download statistics about how often in a given month the project's product and other artifact have been downloaded. The data is available in .JSON format. - - **Site Source Checker**: Use this screen to locate and review the source files for an ASF project's website. Yellow or red indicators tell you that the site they are attached to is not currently being updated. +- **Uptime Statistics**: This dashboard provides an overview of uptime of a wide range of services, including email, forums and Confluence wikis, version control systems, and websites. +- **Public Download Statistics**: On this screen you can select an ASF project and then review and download statistics about how often in a given month the project's product and other artifact have been downloaded. The data is available in .JSON format. +- **Site Source Checker**: Use this screen to locate and review the source files for an ASF project's website. Yellow or red indicators tell you that the site they are attached to is not currently being updated. ## Reports available to the Infra team and/or ASF Members - - **Jira tickets**: Infra uses this dashboard to track resolution of Jira tickets related to infrastructure work. Gauges and charts cover how quickly issues are resolved and whether the number of open tickets for Jira is increasing or decreasing, and provides a drive-by view of all open Jira tickets. - - **Mail Transport Statistics**: This screen, for the Infrastructure team, gives a visualization of how the system is handling ASF and project email. - - **Real-time Download Stats**: On this screen, an ASF Member or Committer can select a project to which they belong and get a series of informative charts (over time, by country, by artifact) of downloads of the project's released artifacts. - - **GitHub Actions Usage**: This screen displays the use of GitHub Actions for projects you belong to. The chart can be configured for project (if you belong to more than one), time range and other options. +- **Jira tickets**: Infra uses this dashboard to track resolution of Jira tickets related to infrastructure work. Gauges and charts cover how quickly issues are resolved and whether the number of open tickets for Jira is increasing or decreasing, and provides a drive-by view of all open Jira tickets. +- **Mail Transport Statistics**: This screen, for the Infrastructure team, gives a visualization of how the system is handling ASF and project email. +- **Real-time Download Stats**: On this screen, an ASF Member or Committer can select a project to which they belong and get a series of informative charts (over time, by country, by artifact) of downloads of the project's released artifacts. +- **GitHub Actions Usage**: This screen displays the use of GitHub Actions for projects you belong to. The chart can be configured for project (if you belong to more than one), time range and other options. Send questions or suggestions about the dashboard to `users@infra.apache.org`. diff --git a/content/pages/infra-volunteer.md b/content/pages/infra-volunteer.md index 614077f2c..acbdff6d6 100644 --- a/content/pages/infra-volunteer.md +++ b/content/pages/infra-volunteer.md @@ -5,13 +5,13 @@ There are plenty of opportunities for you to help out with the small tasks Infra There are some basic things you could do if you're going to help out with the ASF Infrastructure team. You probably do some or all of these tasks already in your ASF project. - - Read infrastructure mailing lists and be aware of what is going on. Read #asfinfra as well in the ASF Slack space. - - Work on documentation, especially procedural documentation and answers to FAQs. Everybody saves time if committers, contributors and PMCs can consult web pages that have most of the information they ask for most of the time.. - - Answer questions that other people ask on users@infra.apache.org. This is immensely beneficial to the rest of the team, as it frees them up to get on with other things. - - Work through the Jira Issue Tracker and submit patches, comments, links, etc. that may help in resolving them. - - Look for support requests on users@infra.apache.org as they come in and volunteer to handle them. - - Add entries to the Issue Tracker for issues raised via e-mail that are not yet being handled. We don't want them slipping through the cracks. - - Work on in-house tasks. At any time there are several outstanding TODOs involving general documentation, in-house services, patches, and scripts; not everything is recorded on the issue tracker. +- Read infrastructure mailing lists and be aware of what is going on. Read #asfinfra as well in the ASF Slack space. +- Work on documentation, especially procedural documentation and answers to FAQs. Everybody saves time if committers, contributors and PMCs can consult web pages that have most of the information they ask for most of the time.. +- Answer questions that other people ask on users@infra.apache.org. This is immensely beneficial to the rest of the team, as it frees them up to get on with other things. +- Work through the Jira Issue Tracker and submit patches, comments, links, etc. that may help in resolving them. +- Look for support requests on users@infra.apache.org as they come in and volunteer to handle them. +- Add entries to the Issue Tracker for issues raised via e-mail that are not yet being handled. We don't want them slipping through the cracks. +- Work on in-house tasks. At any time there are several outstanding TODOs involving general documentation, in-house services, patches, and scripts; not everything is recorded on the issue tracker. **Visit** this Wiki page for details about all the lovely infrastructure tasks waiting for volunteers. diff --git a/content/pages/jira-account-retention-policy.md b/content/pages/jira-account-retention-policy.md index 5d0758296..f25c2c7ad 100644 --- a/content/pages/jira-account-retention-policy.md +++ b/content/pages/jira-account-retention-policy.md @@ -7,7 +7,7 @@ As of April, 2025, the ASF had 99,115 Jira accounts that had been inactive for m This volume of accounts puts an unnecessary burden on our system, and Infra will be taking steps to: - - delete accounts that are more than a year old and have never had any activity. - - disable and anonymize accounts that have been inactive for the past three years, retaining the record of their activity before that time. +- delete accounts that are more than a year old and have never had any activity. +- disable and anonymize accounts that have been inactive for the past three years, retaining the record of their activity before that time. ASF Members and project committers can help lighten the load by making sure to always use a Jira account with your ASF credentials (username, email address as they appear in the ICLA you submitted) whenever creating or commenting on a ticket for The ASF, or related to any of our projects. diff --git a/content/pages/jira-for-infra.md b/content/pages/jira-for-infra.md index 96e3de2c0..1a70d37b8 100644 --- a/content/pages/jira-for-infra.md +++ b/content/pages/jira-for-infra.md @@ -15,10 +15,10 @@ We need the right information to respond to your work request or bug report. In Infra may respond in a number of ways, including: - - Closing the ticket as **invalid**. Review [Before you create a ticket](jira-guidelines.html#before) for reasons that may generate this response. - - Asking for **further details**. You may then see that the status of the ticket has changed to _waiting for user_. Provide the details as best you can in a comment, and change the status to _waiting for Infra_. - - Closing the ticket as **inactive**. If we set the ticket status to _Waiting for user_ and there is no activity on it for 14 days, the system sends a reminder to the reporter. If there is no activity on the ticket for a further seven days, the system automatically closes it as inactive. - - Reporting the issue **resolved**. Please verify the fix or that the requested service is now available. If all is well, and Infra has not changed the status to _closed_ or one of its variants, feel free to do so yourself. +- Closing the ticket as **invalid**. Review [Before you create a ticket](jira-guidelines.html#before) for reasons that may generate this response. +- Asking for **further details**. You may then see that the status of the ticket has changed to _waiting for user_. Provide the details as best you can in a comment, and change the status to _waiting for Infra_. +- Closing the ticket as **inactive**. If we set the ticket status to _Waiting for user_ and there is no activity on it for 14 days, the system sends a reminder to the reporter. If there is no activity on the ticket for a further seven days, the system automatically closes it as inactive. +- Reporting the issue **resolved**. Please verify the fix or that the requested service is now available. If all is well, and Infra has not changed the status to _closed_ or one of its variants, feel free to do so yourself. ## When Infra will respond @@ -30,6 +30,6 @@ Here are details about Infra's typical [response times](responsetime.html) to Ji The reporter of a ticket should check it regularly to see if it has had activity that requires their response. - - If the status is now _Waiting for User_, Infra may need something for you: additional information, a clarification, testing a fix or, if the ticket is about a problem with infrastructure, a request to verify whether you are still experiencing the problem. Provide the information if you can, or explain why you cannot...and don't forget to change the ticket status to _Waiting for Infra_. - - If the message from Infra is that the work is done or the problem is solved, and you can verify it, add a note to that effect and **close the ticket** as fixed. Do not just abandon it. - - There may be questions or suggestions in the comment thread that you should respond to. +- If the status is now _Waiting for User_, Infra may need something for you: additional information, a clarification, testing a fix or, if the ticket is about a problem with infrastructure, a request to verify whether you are still experiencing the problem. Provide the information if you can, or explain why you cannot...and don't forget to change the ticket status to _Waiting for Infra_. +- If the message from Infra is that the work is done or the problem is solved, and you can verify it, add a note to that effect and **close the ticket** as fixed. Do not just abandon it. +- There may be questions or suggestions in the comment thread that you should respond to. diff --git a/content/pages/jira-guidelines.md b/content/pages/jira-guidelines.md index c0740e36f..b6a1a9635 100644 --- a/content/pages/jira-guidelines.md +++ b/content/pages/jira-guidelines.md @@ -70,11 +70,11 @@ Make your best guess at how urgent this thing is. Infra, and many projects, tria The options are - - **Blocker**: a time-sensitive issue that is hindering a basic function of a project. (_example: "We just announced a new release, but SVN is not allowing us to upload or move the artifacts."_) - - **Critical**: a time-sensitive issue that is disrupting the project, but does not hinder basic functions. (_"Our website has been defaced."_) - - **Major**: this issue needs attention soon, but is not hindering basic functions. Most requests for new resources fall into this category. (_"Add a Git repository."_) - - **Minor**: this issue needs attention, but is not time-sensitive and does not hinder basic functions. (_"Fix a JavaScript error on the website."_) - - **Trivial**: this issue is minimal and has no time constraints. ( _"The copyright year on Infra web page bla.html is incorrect."_) +- **Blocker**: a time-sensitive issue that is hindering a basic function of a project. (_example: "We just announced a new release, but SVN is not allowing us to upload or move the artifacts."_) +- **Critical**: a time-sensitive issue that is disrupting the project, but does not hinder basic functions. (_"Our website has been defaced."_) +- **Major**: this issue needs attention soon, but is not hindering basic functions. Most requests for new resources fall into this category. (_"Add a Git repository."_) +- **Minor**: this issue needs attention, but is not time-sensitive and does not hinder basic functions. (_"Fix a JavaScript error on the website."_) +- **Trivial**: this issue is minimal and has no time constraints. ( _"The copyright year on Infra web page bla.html is incorrect."_) #### Component/s diff --git a/content/pages/key-transition.md b/content/pages/key-transition.md index f7f4d5132..2aa38c298 100644 --- a/content/pages/key-transition.md +++ b/content/pages/key-transition.md @@ -33,8 +33,8 @@ It is best to use a single keyring containing both keys. Generate the new key either: - - directly in the keyring containing the old key - - in a new keyring, and then transfer the new key to the keyring containing the old key +- directly in the keyring containing the old key +- in a new keyring, and then transfer the new key to the keyring containing the old key To generate a strong [RSA key](release-signing.html#rsa) follow [these instructions](openpgp.html#generate-key). If you use a separate keyring, follow [these instructions](openpgp.html#secret-key-transfer) to transfer it. @@ -211,8 +211,8 @@ The final stage in the process is to update documents containing references to t For other documents: - - Update those that contain an [export](release-signing.html#export) with a dual export. - - Update those that contain a [fingerprint](release-signing.html#fingerprint") with [both fingerprints](#transition-fingerprints). +- Update those that contain an [export](release-signing.html#export) with a dual export. +- Update those that contain a [fingerprint](release-signing.html#fingerprint") with [both fingerprints](#transition-fingerprints).

Web of trust

@@ -249,7 +249,7 @@ sub 4096R/4A6D5217 2009-08-20 So the fingerprints are: - - `CD0C 5281 D0A9 E963 19AF F365 AD81 612A AD74 1727` for `AD741727` - - `FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8` for `E2B054B8` +- `CD0C 5281 D0A9 E963 19AF F365 AD81 612A AD74 1727` for `AD741727` +- `FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8` for `E2B054B8` For every fingerprint, the last 8 digits are the key ID. diff --git a/content/pages/licensing-howto.md b/content/pages/licensing-howto.md index fd1f27bda..efee31ac0 100644 --- a/content/pages/licensing-howto.md +++ b/content/pages/licensing-howto.md @@ -13,18 +13,18 @@ The `NOTICE` file is described in complete requirements for `LICENSE` and `NOTICE` files are available. - - Guiding principle - - Location - - Step-by-step instructions - - Bundling - - Bundling permissively-licensed dependencies - - Bundling an Apache 2-0 licensed dependency - - Bundling other ASF products - - Bundled vs. non-bundled dependencies - - Dependencies of dependencies - - Modifications to NOTICE - - Binary distributions - - Example NOTICE file +- Guiding principle +- Location +- Step-by-step instructions +- Bundling + - Bundling permissively-licensed dependencies + - Bundling an Apache 2-0 licensed dependency + - Bundling other ASF products + - Bundled vs. non-bundled dependencies + - Dependencies of dependencies +- Modifications to NOTICE +- Binary distributions +- Example NOTICE file

Guiding principle

@@ -38,17 +38,17 @@ The `LICENSE` and `NOTICE` files must **exactly represent** the contents of the To assemble `LICENSE` and `NOTICE` files from scratch for products with complex requirements, follow these steps: - - Copy the full Apache 2.0 license text into a `LICENSE` file. - - Create a 'NOTICE' file specific to your product's details, and complying with the instructions below. An example `NOTICE` file is at the bottom of this page. - - Add any mandatory legal notifications specific to the IP of your product. - - For any bundled dependency, consider whether `LICENSE` and/or `NOTICE` need to be modified. **Do not** modify `LICENSE` or `NOTICE` for non-bundled dependencies. +- Copy the full Apache 2.0 license text into a `LICENSE` file. +- Create a 'NOTICE' file specific to your product's details, and complying with the instructions below. An example `NOTICE` file is at the bottom of this page. + - Add any mandatory legal notifications specific to the IP of your product. + - For any bundled dependency, consider whether `LICENSE` and/or `NOTICE` need to be modified. **Do not** modify `LICENSE` or `NOTICE` for non-bundled dependencies.

Bundling permissively-licensed dependencies

Bundling a dependency which is issued under one of the following licenses is straightforward, assuming that license applies uniformly to all files within the dependency: - - BSD (without advertising clause) - - MIT/X11 +- BSD (without advertising clause) +- MIT/X11 In `LICENSE`, add a pointer to the dependency's license within the distribution and a short note summarizing its licensing: diff --git a/content/pages/mailing-list-moderation.md b/content/pages/mailing-list-moderation.md index 37ca4dbee..d7bf45a97 100644 --- a/content/pages/mailing-list-moderation.md +++ b/content/pages/mailing-list-moderation.md @@ -3,18 +3,18 @@ license: https://www.apache.org/licenses/LICENSE-2.0 Mailing lists are the virtual rooms where ASF communities live, form and grow. All formal decisions the project's PMC makes need to have an email thread (possibly with a recorded vote) as an audit trail that this was an official decision. - - How do we create a new mailing list? - - How do I change moderators? - - How do I find who is subscribed to a list? - - What should I do with MODERATE emails? +- How do we create a new mailing list? +- How do I change moderators? +- How do I find who is subscribed to a list? +- What should I do with MODERATE emails? Dealing with - - MODERATE requests for spam - - allowing posts from non-subscribers - - problem posts - - reports of missing mail - - reports of message bounces +- MODERATE requests for spam +- allowing posts from non-subscribers +- problem posts +- reports of missing mail +- reports of message bounces See also Infra's general guidelines on content moderation. @@ -24,9 +24,9 @@ It is wise to keep the number of mailing lists per codebase the smallest possibl At the same time, as communities grow, the need for more specialized mailing lists appears. If you think your project requires a new list: - - Float the idea in the `dev@` or `users@` mailing list. - - If there seems to be some support for the idea, request a community vote. - - If the community approves adding a mailing list, the PMC chair or another Apache Member on the PMC can do so through the ASF Self-Service Platform +- Float the idea in the `dev@` or `users@` mailing list. +- If there seems to be some support for the idea, request a community vote. +- If the community approves adding a mailing list, the PMC chair or another Apache Member on the PMC can do so through the ASF Self-Service Platform **WARNING**: Creating a user email list can harm a project community if the developers don't pay attention to their users and reply to their emails. One would expect a well-behaving user community to reply to one another in a civil, adult manner that is focused on whatever the list was created for, but it can take time for a community to learn and take to heart such good behavior. @@ -34,19 +34,19 @@ At the same time, as communities grow, the need for more specialized mailing lis You can manage the list of moderators for a project's email list if you are: - - a Foundation member and on the PMC of the project - - chair of the project - - an existing moderator of the list +- a Foundation member and on the PMC of the project +- chair of the project +- an existing moderator of the list - - Log in to WebMod with your ASF credentials. - - Select the 'List moderator management' tab. - - In the dropdown list, select the project which has the email list in question. - - In the list of email lists that appears, select the list whose moderators you want to manage. + - Log in to WebMod with your ASF credentials. + - Select the 'List moderator management' tab. + - In the dropdown list, select the project which has the email list in question. + - In the list of email lists that appears, select the list whose moderators you want to manage. The current list of moderators for this list appears. You can: - - **Remove a moderator**: Click the `Remove as moderator` link beside their name. - - **Add a moderator**: In the `Add a moderator` field, enter the email address of the new moderator. Make sure this is an address that the person has registered with the ASF. +- **Remove a moderator**: Click the `Remove as moderator` link beside their name. +- **Add a moderator**: In the `Add a moderator` field, enter the email address of the new moderator. Make sure this is an address that the person has registered with the ASF. To determine who the existing moderators are, any committer can use the technique described in the "committers" SVN module at resources.txt. @@ -76,10 +76,10 @@ You can review and manage email that is waiting for moderation in two ways: WebMod simplifies reviewing and responding to emails that require moderation. - - Log in to WebMod using your Apache credentials. - - A tab appears for each email list for which you are a moderator and that has emails needing review. Select a tab. - - You can approve or reject multiple emails in one action by checking the checkboxes to the left of the email titles and selecting either `accept` or `spam` from the bulk-actions dropdown list. - - You have many options for reviewing each individual email, including displaying just the text body or viewing the source. The options appear as links to the right of the email title. +- Log in to WebMod using your Apache credentials. +- A tab appears for each email list for which you are a moderator and that has emails needing review. Select a tab. +- You can approve or reject multiple emails in one action by checking the checkboxes to the left of the email titles and selecting either `accept` or `spam` from the bulk-actions dropdown list. +- You have many options for reviewing each individual email, including displaying just the text body or viewing the source. The options appear as links to the right of the email title. #### Manual moderation diff --git a/content/pages/mfa-reset.md b/content/pages/mfa-reset.md index 19cb26d05..ca010fcfc 100644 --- a/content/pages/mfa-reset.md +++ b/content/pages/mfa-reset.md @@ -15,9 +15,9 @@ There are two paths to recovery if you have lost your MFA token(s): To keep this process low-friction, we strongly encourage committers to register multiple factors in advance: - - *Save the recovery codes provided during MFA setup.* - - Upload a valid GPG public key to id.apache.org. - - Link their ASF and GitHub accounts via Boxer. +- *Save the recovery codes provided during MFA setup.* +- Upload a valid GPG public key to id.apache.org. +- Link their ASF and GitHub accounts via Boxer. If a committer cannot establish their identity through any of their registered factors or through any other Infra-established process, the affected account will be **disabled**, and the committer will need to work with their project to be onboarded again through the new-committer process. diff --git a/content/pages/mfa.md b/content/pages/mfa.md index 66c5a2a1f..122eff48a 100644 --- a/content/pages/mfa.md +++ b/content/pages/mfa.md @@ -9,8 +9,8 @@ ASF project committers will encounter MFA when they set up their accounts to wor The Infra team is expanding its use of ASF MFA to cover ASF applications and processes. Committers will be prompted to enroll in ASF MFA when accessing a service which uses that system. The method for setting up ASF MFA is similar to the current GitHub experience. To ensure smooth enrollment in The ASF's MFA system, committers can prepare by: - - Using an existing feature at id.apache.org to upload their GPG public key. This gives the committer an additional factor Infra can rely on during account recovery. - - Linking their ASF and GitHub accounts via Boxer. This establishes a verifiable relationship between the two accounts. +- Using an existing feature at id.apache.org to upload their GPG public key. This gives the committer an additional factor Infra can rely on during account recovery. +- Linking their ASF and GitHub accounts via Boxer. This establishes a verifiable relationship between the two accounts. Committers and ASF Members can consult in-development user documentation at s.apache.org/mfa-user-guide. diff --git a/content/pages/new-committers-guide.md b/content/pages/new-committers-guide.md index 9bab4250f..edce567ad 100644 --- a/content/pages/new-committers-guide.md +++ b/content/pages/new-committers-guide.md @@ -3,25 +3,25 @@ license: https://www.apache.org/licenses/LICENSE-2.0 Here's how to set up the technical and social environment that will support your work as a committer to an Apache project. Some projects have more specific guidelines which the project website or the PMC provide for you. We also have a thorough [Committers' FAQs](committers.html) for both new and experienced committers. - - What is a committer? - - Becoming a committer - - The Committer's Way - - Submitting your Individual Contributor License Agreement (ICLA) - - Acceptance of your ICLA - - Apache Committer account creation - - Set up your @apache.org email address - - Set up Subversion or Git access - - Configure your access to project Git repositories - - Set up Security and PGP Keys - - Committer resources - - the Committers-only Subversion module - - The Apache Community - - Join mailing lists - - Committer responsibilities - - Attending Community Over Code - - Identity theft - - Share your wisdom - - The last word +- What is a committer? +- Becoming a committer + - The Committer's Way + - Submitting your Individual Contributor License Agreement (ICLA) + - Acceptance of your ICLA + - Apache Committer account creation + - Set up your @apache.org email address + - Set up Subversion or Git access + - Configure your access to project Git repositories + - Set up Security and PGP Keys +- Committer resources + - the Committers-only Subversion module +- The Apache Community + - Join mailing lists +- Committer responsibilities +- Attending Community Over Code +- Identity theft +- Share your wisdom +- The last word

What is a committer?

@@ -31,9 +31,9 @@ The plain sense of the word "committer" is that you have access rights to your p If you are not yet a committer, but would like to become one, review: - - Become a committer - - ASF committers - - Meritocracy +- Become a committer +- ASF committers +- Meritocracy

The Committer's Way

@@ -47,11 +47,11 @@ Take more care than you may have done before when working on the code, since you If you are a brand-new committer, you must complete and submit an Individual Contributor License Agreement (ICLA) before the ASF can activate your committer account. Note that an account can only be created if a PMC (or Incubator podling) has invited you. The ICLA is a formal contract that declares the terms under which you will contribute intellectual property to the ASF. Note that the ICLA does not assign copyright to the ASF; you retain copyright to your own work. However it does grant the ASF sufficient rights to release any work you submit under the Apache license.

- - Choose an Apache ID before submitting your ICLA. Also select an alternative, in case the ID you want is unsuitable or already taken. Your ID must consist of at least three lower-case alphanumeric characters, starting with a letter. (This list shows the IDs that are already taken.) - - Identify your project (PMC or incubator podling). - - **IMPORTANT**: you may need to hold discussions with your employer before signing the ICLA, since your employer may have rights to the coding work you do, even outside of your employment. Your employer might even need to provide a Corporate CLA - determining that is your responsibility. Make sure that you keep up-to-date with this requirement. - - Read and understand the agreements ICLA specifies and strive to meet the standards expected. Correct title to code sources is of great importance to ASF and it must be to you, too. - - Make sure that any code you contribute is original work, and that you publicly contribute it to the ASF. In the case of any doubt (or when a contribution has a complex history) please consult your project PMC before committing it. +- Choose an Apache ID before submitting your ICLA. Also select an alternative, in case the ID you want is unsuitable or already taken. Your ID must consist of at least three lower-case alphanumeric characters, starting with a letter. (This list shows the IDs that are already taken.) +- Identify your project (PMC or incubator podling). +- **IMPORTANT**: you may need to hold discussions with your employer before signing the ICLA, since your employer may have rights to the coding work you do, even outside of your employment. Your employer might even need to provide a Corporate CLA - determining that is your responsibility. Make sure that you keep up-to-date with this requirement. +- Read and understand the agreements ICLA specifies and strive to meet the standards expected. Correct title to code sources is of great importance to ASF and it must be to you, too. +- Make sure that any code you contribute is original work, and that you publicly contribute it to the ASF. In the case of any doubt (or when a contribution has a complex history) please consult your project PMC before committing it. Some procedures may appear a little bureaucratic, but they are there to protect you as well as ASF. For a clearer understanding read the ASF license guide. @@ -65,10 +65,10 @@ You will also need to familiarize yourself with some Apache policies and procedu Key Committer resources: - - ASF Developer Guides & Resources contains pointers to the most important information - - the ASF How it works document - - the Apache Training (Incubating) pages - - the ASF Bylaws +- ASF Developer Guides & Resources contains pointers to the most important information +- the ASF How it works document +- the Apache Training (Incubating) pages +- the ASF Bylaws

Apache Committer account creation

@@ -140,8 +140,8 @@ Taking part in the community makes Apache fun. The here. diff --git a/content/pages/nightlies.md b/content/pages/nightlies.md index da03c027f..c30441f68 100644 --- a/content/pages/nightlies.md +++ b/content/pages/nightlies.md @@ -12,13 +12,13 @@ were otherwise kept on `ci-builds.apache.org` (was `builds.apache.org`) along wi nightlies, as implied by its name, is designed as a 'short term' storage solution. Examples of how projects use the service are: - - Nightly Snapshots of trunk/main builds for developer-only testing. - - Different website versions - e.g : trunk/main/bleeding edge docs , RC1, $latest release version, $previous release version. - - Javadocs / Api Docs. - - Logs of jobs. - - Artifacts, packages as created by a build or builds. - - Historical data for analysis, graphing etc. - - A generated index.html to your sub-directories of data. +- Nightly Snapshots of trunk/main builds for developer-only testing. +- Different website versions - e.g : trunk/main/bleeding edge docs , RC1, $latest release version, $previous release version. +- Javadocs / Api Docs. +- Logs of jobs. +- Artifacts, packages as created by a build or builds. +- Historical data for analysis, graphing etc. +- A generated index.html to your sub-directories of data. **Note**: nightlies is **not an official release channel**. Do not place product release artifacts here. Please review Apache's release distribution policy, especially the section on release channels. diff --git a/content/pages/open-access-svn.md b/content/pages/open-access-svn.md index cd73a30ce..5985297e5 100644 --- a/content/pages/open-access-svn.md +++ b/content/pages/open-access-svn.md @@ -14,30 +14,30 @@ ability (but not the social privilege) to make commits against any part of the `

Upsides

- - Simplifies administration of SVN ACL. - - Allows more cross-collaboration into participating projects. - - Changes the culture from a set of technically-closed communities to a set of mostly-open ones. +- Simplifies administration of SVN ACL. +- Allows more cross-collaboration into participating projects. +- Changes the culture from a set of technically-closed communities to a set of mostly-open ones.

Downsides

- - PMCs no longer control who has commit privileges (technically untrue. They are simply being asked to use blacklists instead of whitelists). - - Increases leverage for abusive behavior, though this is mitigated by the relative ease by which bad commits can be reverted via reverse-merging, or, for more invasive changes, plastering over them by deleting the entire tree and copying the last known good revision to HEAD. This only starts getting complicated when good commits start being mingled with bad ones. - - One hacked account can damage all of `/repos/asf` (disregard for basic tenet of security: provide access only to those who require it and only to the bare minimum of what they need). - - May lead to confusion about the distinction between technical and social privileges. - - No single usable accounting of who on a PMC has commit permissions. Impact on non SVN-related resources for PMC and foundation (example: `https://people.apache.org/committer-index.html`). - - Increases workload on PMCs and volunteer committers. - - Creates a precedent where the foundation imposes its will on PMCs for no clearly defined or overwhelming reason (also technically untrue as allowances will be made for grandfathering projects). +- PMCs no longer control who has commit privileges (technically untrue. They are simply being asked to use blacklists instead of whitelists). +- Increases leverage for abusive behavior, though this is mitigated by the relative ease by which bad commits can be reverted via reverse-merging, or, for more invasive changes, plastering over them by deleting the entire tree and copying the last known good revision to HEAD. This only starts getting complicated when good commits start being mingled with bad ones. +- One hacked account can damage all of `/repos/asf` (disregard for basic tenet of security: provide access only to those who require it and only to the bare minimum of what they need). +- May lead to confusion about the distinction between technical and social privileges. +- No single usable accounting of who on a PMC has commit permissions. Impact on non SVN-related resources for PMC and foundation (example: `https://people.apache.org/committer-index.html`). +- Increases workload on PMCs and volunteer committers. +- Creates a precedent where the foundation imposes its will on PMCs for no clearly defined or overwhelming reason (also technically untrue as allowances will be made for grandfathering projects).

Participating Projects

- - Lucy - - Onami - - Subversion - - Bloodhound - - Hadoop Developer Tools - - Helix - - Kalumet - - Infra buildbot config +- Lucy +- Onami +- Subversion +- Bloodhound +- Hadoop Developer Tools +- Helix +- Kalumet +- Infra buildbot config

Alternate proposal 1

@@ -51,8 +51,8 @@ It would be wonderful from an Infra standpoint, if this alternate proposal gains The proposal from bimargulies here rests on two foundations: - - Streamline administration - - Push projects towards a more open view of participation +- Streamline administration +- Push projects towards a more open view of participation Changing the authz scheme can give projects a push. However, we have many other possible means of encouraging projects to adopt a more open approach. `SCM authz` is a tool that the foundation provides to help projects manage themselves. The theory is that many projects could benefit from a shift in attitude toward authz and even commit rights. However, 'many' is not all. I've been talking to someone who might bring a project to the incubator. This project builds software that has very strict assurance requirements. If they were to come, they would probably feel the need to manage a tight ACL. In discussions, it seems to me that existing projects that are far along the sequence towards, 'a stable product that evolves very cautiously' are less likely to adopt an open ACL. diff --git a/content/pages/openpgp.md b/content/pages/openpgp.md index ff0ebbeb8..2d8adb521 100644 --- a/content/pages/openpgp.md +++ b/content/pages/openpgp.md @@ -3,22 +3,22 @@ license: https://www.apache.org/licenses/LICENSE-2.0 ### Contents ### - - Introduction - - Gnu Privacy Guard - - How to generate a strong key - - Private keyring management +- Introduction +- Gnu Privacy Guard +- How to generate a strong key +- Private keyring management How to... - - find a key ID - - back up keys - - export a key - - transfer a secret key - - transition from an old to a new key - - use revocation certificates - - use symmetric encryption - - update Apache documents with details of a new key - - use the Web of Trust +- find a key ID +- back up keys +- export a key +- transfer a secret key +- transition from an old to a new key +- use revocation certificates +- use symmetric encryption +- update Apache documents with details of a new key +- use the Web of Trust

Introduction

@@ -84,9 +84,9 @@ clients lack `SHA512` support, we recommend switching to `SHA512` if possible. To configure `gpg` to avoid SHA-1, edit the options in [`gpg.conf`](#configuration). Options need to be added or given the correct values for: - - `cert-digest-algo` - the certificate digest used when linking into the [web of trust](release-signing.html#link-into-wot) - - `personal-digest-preferences` - the digest used for [signing messages](release-signing.html#detach-sig) - - `default-preference-list` - the default algorithm preferences for [new keys](release-signing.html#generate) (this does not affect existing keys: see next paragraph) +- `cert-digest-algo` - the certificate digest used when linking into the [web of trust](release-signing.html#link-into-wot) +- `personal-digest-preferences` - the digest used for [signing messages](release-signing.html#detach-sig) +- `default-preference-list` - the default algorithm preferences for [new keys](release-signing.html#generate) (this does not affect existing keys: see next paragraph) To use `SHA512` (recommended): @@ -171,8 +171,8 @@ than 4096 bits, GnuPG comes in two flavors. To easily generate a 4096 bit RSA signing and encryption key pair with strong digests, use either GnuPG version: - - `2.0.12` or higher (well-known, portable version) - - `1.4.10` or higher (version with advanced features) +- `2.0.12` or higher (well-known, portable version) +- `1.4.10` or higher (version with advanced features) Once you generate the key, you can use it with the widely available `1.4.9` and `2.x` releases. @@ -376,7 +376,7 @@ If you are generating a key for use in a [transition](release-signing.html#trans If this is a new code signing key not involved with a transition: - 1. [Upload](release-signing.html#keyserver-upload) the new [public key](release-signing.html#public-private) to a public + 1. [Upload](release-signing.html#keyserver-upload) the new [public key](release-signing.html#public-private) to a public [keyserver](release-signing.html#keyserver) 1. Create backups by following these [instructions](#backup) @@ -488,10 +488,10 @@ The [key ID](release-signing.html#key-id) is not confidential but without access So, for each [key pair](release-signing.html#public-private) you generate, the [key ID](release-signing.html#key-id) needs to recorded in a form that makes tampering difficult. Defense in depth is the best strategy. We recommend that you use a range of methods:: - - Print a hard copy of the key ID and store it securely - - Include the key ID on your business cards - - ASF Members should include the key ID on their Apache business cards - - Include a text document containing the key ID in your [secure, tamperproof private backups](#backup-private) +- Print a hard copy of the key ID and store it securely +- Include the key ID on your business cards +- ASF Members should include the key ID on their Apache business cards +- Include a text document containing the key ID in your [secure, tamperproof private backups](#backup-private)

Back up private information

@@ -505,8 +505,8 @@ Choose a strong passphrase. If this is not possible then use strong, [symmetric] We recommend a removable medium type with good long term storage characteristics: - - A small capacity, high quality USB flash drive - - A CDROM +- A small capacity, high quality USB flash drive +- A CDROM Make and securely store multiple copies. @@ -652,9 +652,9 @@ store](release-signing.html#revocation-certificate-storage) generic revocation c When you create a new [key pair](release-signing.html#public-private), also generate and store generic revocation certificates for that key pair. We recommend that you generate a certificate (following the instructions in the next section) for each appropriate revocation reason type: - - No reason specified - - Key has been compromised - - Key is no longer used +- No reason specified +- Key has been compromised +- Key is no longer used Note that *Key is superseded* is not appropriate for a new key since it is not possible to know which key will replace it. @@ -669,10 +669,10 @@ Revocation certificates include a small amount of additional information" One of four machine readable reason types: - - No reason specified - *a catch-all category* - - Key has been compromised - *also use this if you believe that the key may have been compromised (for example, when a storage device containing the private key has been lost)* - - Key is superseded - *the comment should suggest the replacement key* - - Key is no longer used - *useful when the key has been destroyed and so a generic revocation prepared earlier must be used* +- No reason specified - *a catch-all category* +- Key has been compromised - *also use this if you believe that the key may have been compromised (for example, when a storage device containing the private key has been lost)* +- Key is superseded - *the comment should suggest the replacement key* +- Key is no longer used - *useful when the key has been destroyed and so a generic revocation prepared earlier must be used* The certificate also includes a human-readable *comment*. Explain here the reason why you are revoking the key. This lets those affected by the revocation to formulate an appropriate response. @@ -818,13 +818,13 @@ For example, this ho To create an [ASCII armored](release-signing.html#ascii) [public key](release-signing.html#public-private) [export](release-signing.html#export): - - When using a [transition](release-signing.html#transition), follow these [instructions](key-transition.html#transition-export). - - Otherwise this [discussion](#export-key) describes how to export public keys. +- When using a [transition](release-signing.html#transition), follow these [instructions](key-transition.html#transition-export). +- Otherwise this [discussion](#export-key) describes how to export public keys. To find the [fingerprint](release-signing.html#fingerprint) for a key: - - When using a [transition](release-signing.html#transition), follow these [instructions](key-transition.html#transition-fingerprints). - - Otherwise use `gpg --fingerprint`. +- When using a [transition](release-signing.html#transition), follow these [instructions](key-transition.html#transition-fingerprints). +- Otherwise use `gpg --fingerprint`. Ensure that each `pubkeyAddress` points to the new export [uploaded into your Apache home web space](#publish-in-web-space). @@ -853,8 +853,8 @@ Projects maintain [KEYS](release-signing.html#keys-policy) files containing the To create an [ASCII armored](release-signing.html#ascii) [export](release-signing.html#export): - - When using a [transition](release-signing.html#transition), follow these [instructions](key-transition.html#transition-export). - - Otherwise this [discussion](#export-key) describes how to export public keys +- When using a [transition](release-signing.html#transition), follow these [instructions](key-transition.html#transition-export). +- Otherwise this [discussion](#export-key) describes how to export public keys If there is an older export in the `KEYS` file, only remove it if it has not been used to sign a release. It is important that the KEYS file can also be used to check archived releases. @@ -882,8 +882,8 @@ Verifying identities is usually automated, but here is an example to explain the Take Alice, Bob and Charlie. Alice has verified Bob's identity in person. Bob has verified Charlie's identity in person. But Alice has never met Charlie. So - - Bob's key has been signed by Alice's key - - Charlie's key has been signed by Bob's key +- Bob's key has been signed by Alice's key +- Charlie's key has been signed by Bob's key Alice has obtained a file ( `document` in this example) which Charlie may have created, and a detached signature for that file ( `document.asc` in this example). Alice wishes to discover whether Charlie signed this file. @@ -955,8 +955,8 @@ Most clients allow automation of this process of transitive trust resolution. Th It is vital that Apache code signing keys are linked into a strong [web of trust](release-signing.html#web-of-trust). This allows independent verification of the fidelity of Apache releases by anyone strongly linked to this web. In particular, this lets two important groups independently verify releases: - - The Apache Infrastructure Team - - Downstream packagers +- The Apache Infrastructure Team +- Downstream packagers The Apache web of trust is reasonably well connected to the wider-open source web of trust. Though every opportunity should be taken to link into wider networks, the most important action needs to be to plan to exchange signatures with other Apache committers. @@ -982,9 +982,9 @@ Subscribe to the party list (see committer documentation) to find out about info In short, expect that: - - this will involve a face-to-face meeting - - you will have to provide some sort of real-world identification, like a driver's license - - you will be asked to verify their identity and sign their public key in +- this will involve a face-to-face meeting +- you will have to provide some sort of real-world identification, like a driver's license +- you will be asked to verify their identity and sign their public key in exchange Bring the key [fingerprint](release-signing.html#fingerprint) but keep the private key safely at home. @@ -999,11 +999,11 @@ The most effective way to achieve this is to attend a [key signing party](releas Expect to: - - bring identification - - bring a hard copy of your key's [fingerprint](release-signing.html#fingerprint) - - supply the key ID or public key to the organiser before the party - - check that the [fingerprint](release-signing.html#fingerprint) for your key supplied by the organiser matches your hard copy - - confirm this to those present +- bring identification +- bring a hard copy of your key's [fingerprint](release-signing.html#fingerprint) +- supply the key ID or public key to the organiser before the party +- check that the [fingerprint](release-signing.html#fingerprint) for your key supplied by the organiser matches your hard copy +- confirm this to those present Do **not** bring your private key. This **must** stay safe and secure at all times. Wait until the conference has finished and you have returned home before signing keys. diff --git a/content/pages/os-upgrade-policy.md b/content/pages/os-upgrade-policy.md index cc427dd73..b95122151 100644 --- a/content/pages/os-upgrade-policy.md +++ b/content/pages/os-upgrade-policy.md @@ -5,8 +5,8 @@ Infra supports Ubuntu long-term support (LTS) releases and Windows platforms. Some services are on a virtual machine (VM) on a host physical server, and some services run on "bare metal". - - When we move to a new machine running Ubuntu, we install the current stable version of the operating system. - - Windows servers typically run Windows Server 2016 Standard. As we replace older physical machines with newer ones, we install the most recent stable version of Windows Server Standard that is available at the time of migration. - - ASF Windows desktops typically run Windows 10 Professional. The migration pattern is as for the servers. - - For builds, we run Buildbot on Windows desktops and Jenkins on Windows servers. +- When we move to a new machine running Ubuntu, we install the current stable version of the operating system. +- Windows servers typically run Windows Server 2016 Standard. As we replace older physical machines with newer ones, we install the most recent stable version of Windows Server Standard that is available at the time of migration. +- ASF Windows desktops typically run Windows 10 Professional. The migration pattern is as for the servers. +- For builds, we run Buildbot on Windows desktops and Jenkins on Windows servers. \ No newline at end of file diff --git a/content/pages/pelican-buildbot.md b/content/pages/pelican-buildbot.md index 5f136c0e1..90fd10215 100644 --- a/content/pages/pelican-buildbot.md +++ b/content/pages/pelican-buildbot.md @@ -15,12 +15,12 @@ The repository structure for your Pelican project website has three key director The directories are: - - **content/pages**: holds the static pages for your website. You write and edit them using GFM. - - Each page is a `.md` file. - - The first line is `Title:` and the name of the page. - - the second line is `Date:` and the date of the current version of the page. - - **content/articles**: if your website has a blog or a series of featured articles, they go in this directory and will appear on the front page of the site. They have the same three requirements as the static pages, above. - - **theme/plugins**: holds the plugins Pelican and Buildbot use to build and deploy the site. +- **content/pages**: holds the static pages for your website. You write and edit them using GFM. + - Each page is a `.md` file. + - The first line is `Title:` and the name of the page. + - the second line is `Date:` and the date of the current version of the page. +- **content/articles**: if your website has a blog or a series of featured articles, they go in this directory and will appear on the front page of the site. They have the same three requirements as the static pages, above. +- **theme/plugins**: holds the plugins Pelican and Buildbot use to build and deploy the site. The configuration file is `pelicanconf.py`. diff --git a/content/pages/phishing.md b/content/pages/phishing.md index da97c463a..d151a1fa6 100644 --- a/content/pages/phishing.md +++ b/content/pages/phishing.md @@ -32,9 +32,9 @@ Your best actions are to: Further, -- Do not divulge your credentials to any service outside of **apache.org**. -- In any email claiming to come from an apache.org address, do not click on any 'reset' or 'reauthenticate' links. We never ask you to do this. -- If you think you have been a victim of phishing, reset your ASF password at id.apache.org. +- Do not divulge your credentials to any service outside of **apache.org**. +- In any email claiming to come from an apache.org address, do not click on any 'reset' or 'reauthenticate' links. We never ask you to do this. +- If you think you have been a victim of phishing, reset your ASF password at id.apache.org. If you are unsure whether an email is actually from the ASF, [contact the Infra team](contact.html). Better safe than sorry! diff --git a/content/pages/project-repo-policy.md b/content/pages/project-repo-policy.md index f0e081304..6203a5865 100644 --- a/content/pages/project-repo-policy.md +++ b/content/pages/project-repo-policy.md @@ -3,11 +3,11 @@ license: https://www.apache.org/licenses/LICENSE-2.0 Each Apache project can have a directory in the Apache Subversion repository, or Git repositories, for their product code and assets. The majority of projects now use Git. - - Each project can have a public directory in the Subversion repository, or as many public Git repositories as their work requires. - - Each project can request (using a Jira ticket) that Infra set up **a temporary private Git repository fork** for use with tasks, such as fixing security issues in project code, that should not be publicly available. The PMC must explain its need of a private fork in the Jira ticket. Forks will be tied to Jira tickets or CVEs such that upon completion of the work, the private fork can be decommissioned by Infra. - - Private repos **must** have commit/PR/issues emails sent to the project's `private@` list. - - To follow the Infra convention, name project repos in the pattern `$project-$reponame` in order to map the project LDAP group to the permissions scheme. - - The private repository is **not** for uses such as project code development not related to a security issue. The resources available to run GitHub Actions against private repo code are extremely limited, so use for CI must be kept to the absolute bare minimum. +- Each project can have a public directory in the Subversion repository, or as many public Git repositories as their work requires. +- Each project can request (using a Jira ticket) that Infra set up **a temporary private Git repository fork** for use with tasks, such as fixing security issues in project code, that should not be publicly available. The PMC must explain its need of a private fork in the Jira ticket. Forks will be tied to Jira tickets or CVEs such that upon completion of the work, the private fork can be decommissioned by Infra. +- Private repos **must** have commit/PR/issues emails sent to the project's `private@` list. +- To follow the Infra convention, name project repos in the pattern `$project-$reponame` in order to map the project LDAP group to the permissions scheme. +- The private repository is **not** for uses such as project code development not related to a security issue. The resources available to run GitHub Actions against private repo code are extremely limited, so use for CI must be kept to the absolute bare minimum. ### Git repositories @@ -21,19 +21,19 @@ Each Apache project can have a directory in the Apache Subversion repository, or Git offers a number of customizations for committing code to a repository. Apache does not support all of them for its projects. For instance: - - **supported** - - Head branches automatically deleted after pull requests are merged. - - Commit squashing for pull requests. - - Default to pull request titles for squash commits. - - Commit merging for pull requests. - - Commit rebasing for pull requests. - - Always update a pull request branch when it is not up to date with the base branch. +- **supported** + - Head branches automatically deleted after pull requests are merged. + - Commit squashing for pull requests. + - Default to pull request titles for squash commits. + - Commit merging for pull requests. + - Commit rebasing for pull requests. + - Always update a pull request branch when it is not up to date with the base branch. To deploy one of these customizations for your project's repository, ask Infra for help via a Jira ticket. - - **not supported** - - Auto-merge of pull requests. - - Merge queues. This feature is in limited beta. +- **not supported** + - Auto-merge of pull requests. + - Merge queues. This feature is in limited beta. ### Subversion directories diff --git a/content/pages/project-site.md b/content/pages/project-site.md index 9066c28f4..49a013b45 100644 --- a/content/pages/project-site.md +++ b/content/pages/project-site.md @@ -18,18 +18,18 @@ Your project team wants to build an excellent application that solves a problem, Your website **must** - - satisfy the Apache branding requirements, in particular that certain links appear on the site's landing page, in whatever navigation structure the site uses. Whimsy's Apache Project Website Checks tool periodically reviews all top-level project (TLP) websites to provide a report on how well they comply with that policy, and to identify issues that a project may need to address. - - comply with the Infrastructure team's [project site policy](project-site-policy.html). +- satisfy the Apache branding requirements, in particular that certain links appear on the site's landing page, in whatever navigation structure the site uses. Whimsy's Apache Project Website Checks tool periodically reviews all top-level project (TLP) websites to provide a report on how well they comply with that policy, and to identify issues that a project may need to address. +- comply with the Infrastructure team's [project site policy](project-site-policy.html). The site also **should** - - explain what your project's product does. - - pitch how your product solves a problem or creates a new opportunity. - - invite people to get involved in the development team. - - offer a link to the Apache downloads platform so people can download the latest builds of the product that you want the public to use. - - provide documentation that will help people not part of the project understand how to get started with the product and how to keep going. - - describe how the project team works, and its connection to the Apache Software Foundation. - - explain how people can get in touch with the project to provide feedback or ask questions. +- explain what your project's product does. +- pitch how your product solves a problem or creates a new opportunity. +- invite people to get involved in the development team. +- offer a link to the Apache downloads platform so people can download the latest builds of the product that you want the public to use. +- provide documentation that will help people not part of the project understand how to get started with the product and how to keep going. +- describe how the project team works, and its connection to the Apache Software Foundation. +- explain how people can get in touch with the project to provide feedback or ask questions. Once you have outlined the content that will be on the website, and decided how and where to display it, you need to decide how to build the site. @@ -88,10 +88,10 @@ Infra is migrating the websites of projects using the Pelican option to GitHub A Pelican is a static site generator written in Python. Highlights include: - - Write your content directly with your editor of choice in reStructuredText or Markdown formats. - - Includes a simple CLI tool to (re)generate your site. - - Easy to interface with distributed version control systems and web hooks. - - Completely static output is easy to host anywhere. +- Write your content directly with your editor of choice in reStructuredText or Markdown formats. +- Includes a simple CLI tool to (re)generate your site. +- Easy to interface with distributed version control systems and web hooks. +- Completely static output is easy to host anywhere. Pelican has paths to migrate existing websites from many technologies, including Blogger, Dotclear, Posterous, Tumblr, WordPress, and RSS/Atom. @@ -156,25 +156,25 @@ For more detailed procedures, see see [.asf.yaml](asf-yaml.html). The basic requirements for site management are that - - only committers should be able to modify the site. - - notifications of all site changes are sent to the relevant project mailing lists. +- only committers should be able to modify the site. +- notifications of all site changes are sent to the relevant project mailing lists.

Management tools

Infra supports these tools for publishing and maintaining Apache project websites: - - **[Site template](asf-pelican.html)** streamlines migration of an existing project site on the deprecated CMS, and creation of new project sites. - - **[Pelican and BuildBot](pelican-buildbot.html)** streamline creating and publishing your project website. - - **svnpubsub** automatically publishes the static contents of a designated svn folder (example) as the project web site at `http://project.apache.org`. The project team can use any site build mechanism it wants as long as the above requirements are met. - - [**pypubsub**](pypubsub.html) automatically serves the static contents of a designated Git repository as the website for a project. Git-based websites are typically maintained in a repository branch to be published as `https://project.apache.org`. A project can host the site from its primary project repository. Typically these will be built as a Jenkins or a Buildbot job (see below). We recommend that you only have a single writer to the asf-site branch to avoid potential conflicts. - - For **websites using a Git repository**, you can add an [.asf.yaml](asf-yaml.html) configuration file. The file lets you set instructions that simplify updating and maintaining the site. +- **[Site template](asf-pelican.html)** streamlines migration of an existing project site on the deprecated CMS, and creation of new project sites. +- **[Pelican and BuildBot](pelican-buildbot.html)** streamline creating and publishing your project website. +- **svnpubsub** automatically publishes the static contents of a designated svn folder (example) as the project web site at `http://project.apache.org`. The project team can use any site build mechanism it wants as long as the above requirements are met. +- [**pypubsub**](pypubsub.html) automatically serves the static contents of a designated Git repository as the website for a project. Git-based websites are typically maintained in a repository branch to be published as `https://project.apache.org`. A project can host the site from its primary project repository. Typically these will be built as a Jenkins or a Buildbot job (see below). We recommend that you only have a single writer to the asf-site branch to avoid potential conflicts. +- For **websites using a Git repository**, you can add an [.asf.yaml](asf-yaml.html) configuration file. The file lets you set instructions that simplify updating and maintaining the site. ### Build tools Infra provides these build tools: - - **Jenkins** is an open-source automation server that supports building, deploying and automating a project. Infra resources on Jenkins start here. - - **Buildbot** is a job scheduling system: it queues jobs, executes the jobs when the required resources are available, and reports the results. +- **Jenkins** is an open-source automation server that supports building, deploying and automating a project. Infra resources on Jenkins start here. +- **Buildbot** is a job scheduling system: it queues jobs, executes the jobs when the required resources are available, and reports the results.

Logging

@@ -209,15 +209,15 @@ If you are using `svnpubsub`, the commit performs very slowly if the number of c To speed up the commit: - - When running JavaDoc, pass the `-notimestamp` option. This will avoid most files from being modified between runs if there haven't been code changes. - - Use a Maven skin that doesn't add a timestamp to the output. This may require customizing the current skins. - - If you use the Maven dependencies report in the Project Info Reports plugin, use version 2.7+ of the plugin to avoid random strings being generated. - - If you maintain historical versions of documentation, always check changes in to a single "trunk", then use an `svn copy` operation to tag or branch the content, rather than checking in a complete copy. - - Minimize use of "publish date" and "version" in templates to those that are truly necessary or helpful. Consider using a "last modified date" and version in the URL instead (unless "latest" is implied). - - Minimize Subversion keywords in the output that may change frequently without significant meaning. This includes keywords in source code that may be rendered to JavaDoc or a Maven JXR source cross-reference. - - Avoid publishing Maven reports that change constantly to the project site. Code coverage, style reports, static analysis, etc. can be generated into working copies on the CI server instead for easy developer viewing. +- When running JavaDoc, pass the `-notimestamp` option. This will avoid most files from being modified between runs if there haven't been code changes. +- Use a Maven skin that doesn't add a timestamp to the output. This may require customizing the current skins. +- If you use the Maven dependencies report in the Project Info Reports plugin, use version 2.7+ of the plugin to avoid random strings being generated. +- If you maintain historical versions of documentation, always check changes in to a single "trunk", then use an `svn copy` operation to tag or branch the content, rather than checking in a complete copy. +- Minimize use of "publish date" and "version" in templates to those that are truly necessary or helpful. Consider using a "last modified date" and version in the URL instead (unless "latest" is implied). +- Minimize Subversion keywords in the output that may change frequently without significant meaning. This includes keywords in source code that may be rendered to JavaDoc or a Maven JXR source cross-reference. +- Avoid publishing Maven reports that change constantly to the project site. Code coverage, style reports, static analysis, etc. can be generated into working copies on the CI server instead for easy developer viewing.

Previewing the website

- - For svnpubsub sites, review the local files in your svn checkout before committing them. The changes will be published immediately after you commit them. - - There is no preview mode for `pypubsub`. You should ideally have a way to build and test the website locally. +- For svnpubsub sites, review the local files in your svn checkout before committing them. The changes will be published immediately after you commit them. +- There is no preview mode for `pypubsub`. You should ideally have a way to build and test the website locally. diff --git a/content/pages/publishing-maven-artifacts.md b/content/pages/publishing-maven-artifacts.md index a90cdf919..90e319b8e 100644 --- a/content/pages/publishing-maven-artifacts.md +++ b/content/pages/publishing-maven-artifacts.md @@ -13,18 +13,18 @@ The [ASF Nexus repository](https://repository.apache.org/) enforces security by Before a project can use the repository to release Maven artifacts, it must be configured in Nexus. This is generally a quick and easy process. To get set up, use this link to create a Jira ticket with the following information: - - **Project URL**: a link to your project page (usually `https://.apache.org/`). - - **SVN URL**: where you store your source code, in case Infra needs to look up more information. - - **Maven Group IDs**: a list of the groupIDs for this project. They should all be subgroups of `org.apache`. - - **Managed By This TLP Project**: if this is a subproject, list the TLP that is responsible. Subprojects usually don't have their own LDAP group, so we need the TLP LDAP group for permissions. +- **Project URL**: a link to your project page (usually `https://.apache.org/`). +- **SVN URL**: where you store your source code, in case Infra needs to look up more information. +- **Maven Group IDs**: a list of the groupIDs for this project. They should all be subgroups of `org.apache`. +- **Managed By This TLP Project**: if this is a subproject, list the TLP that is responsible. Subprojects usually don't have their own LDAP group, so we need the TLP LDAP group for permissions. If you have specific questions or concerns, please call them out in the ticket. Once you file the Jira ticket, Infra will do the following: - - **Set up the project in Nexus**: We configure your groupIds in Nexus and link them to the appropriate LDAP group for authorization. - - **Move Existing Artifacts**: To maintain the proper `maven-metadata.xml` files and prevent rsync conflicts in Central, we must move all your artifacts to the new repository. We will mark the folder in the old repository as read-only to prevent accidental deployments. - - **Check POMs**: If your project is Maven-based, we will check your POM for any obvious problems. +- **Set up the project in Nexus**: We configure your groupIds in Nexus and link them to the appropriate LDAP group for authorization. +- **Move Existing Artifacts**: To maintain the proper `maven-metadata.xml` files and prevent rsync conflicts in Central, we must move all your artifacts to the new repository. We will mark the folder in the old repository as read-only to prevent accidental deployments. +- **Check POMs**: If your project is Maven-based, we will check your POM for any obvious problems. ## Adjusting your build to deploy to the ASF Nexus repository ## @@ -107,9 +107,9 @@ mvn deploy **Notes** - - If you experience an error like a _HTTP 401_ during deployment, check your settings for the required server entries as outlined above. - - Be sure that the generated artifacts respect the Apache release rules: NOTICE and LICENSE files should be present in the META-INF directory within the jar. - - Verify the deployment under the ASF Maven Snapshot repository. +- If you experience an error like a _HTTP 401_ during deployment, check your settings for the required server entries as outlined above. +- Be sure that the generated artifacts respect the Apache release rules: NOTICE and LICENSE files should be present in the META-INF directory within the jar. +- Verify the deployment under the ASF Maven Snapshot repository. ### 3. Prepare the release ### @@ -120,10 +120,10 @@ mvn release:prepare **Notes** - - Don't try to publish `.sha256` or `.sha512` files; Nexus doesn't handle them. - - Remove `.md5`s in `dist.apache.org/repos/dist/release/` manually. - - Preparing the release will create a new tag in SVN, and automatically check the version in on your behalf. - - If you're located in Europe, `release:prepare` may fail with `Unable to tag SCM` and `svn: No such revision X`. Wait 10 seconds and run `mvn release:prepare` again. +- Don't try to publish `.sha256` or `.sha512` files; Nexus doesn't handle them. +- Remove `.md5`s in `dist.apache.org/repos/dist/release/` manually. +- Preparing the release will create a new tag in SVN, and automatically check the version in on your behalf. +- If you're located in Europe, `release:prepare` may fail with `Unable to tag SCM` and `svn: No such revision X`. Wait 10 seconds and run `mvn release:prepare` again. ### 4. Stage the release for a vote ### diff --git a/content/pages/qbot.md b/content/pages/qbot.md index 86af84f44..22c0bbcf2 100644 --- a/content/pages/qbot.md +++ b/content/pages/qbot.md @@ -9,10 +9,10 @@ The name references the tool-maker 'Q', who provides weapons and gadgets for Age Qbot has an evolving set of functions: - - Adding people to private channels - - Providing to the channel notifications related to your project's Jira tickets - new ticket, new comment, ticket resolved. - - Displaying information about Jira tickets by project, by keyword, by status (available to ASF Members). - - Starting a question queue in the huddle in a channel workspace. (Note: Infra designed this for use with Roundtable events, in case participants had a flood of questions and comments that would need to be queued so everyone had a fair chance to speak. So far, we have not needed to use it.) +- Adding people to private channels +- Providing to the channel notifications related to your project's Jira tickets - new ticket, new comment, ticket resolved. +- Displaying information about Jira tickets by project, by keyword, by status (available to ASF Members). +- Starting a question queue in the huddle in a channel workspace. (Note: Infra designed this for use with Roundtable events, in case participants had a flood of questions and comments that would need to be queued so everyone had a fair chance to speak. So far, we have not needed to use it.) It also has a set of 'fun' features, such as rolling dice, flipping a coin, or talking to someone from the (fictional) ASF Human Resources Department. @@ -20,14 +20,14 @@ It also has a set of 'fun' features, such as rolling dice, flipping a coin, or t If you want to have Qbot available in your PMC's channel, create a Jira ticket for Infra with the request. Include this information: - - If you want to get Jira-ticket notifications, the name of the channel or channels where notifications about tickets related to your projects should appear - - How you want notifications to appear. There are five options: - - No notifications - - All notifications - - `nodescription`: All notifications with the title of the ticket, but not its description - - `nocomments`: No notifications of comments on tickets - - `createclose`: Just notifications of ticket creation and resolution - - Specify who can use the `addme` command -- committers, members of your PMC only, ASF Members only... +- If you want to get Jira-ticket notifications, the name of the channel or channels where notifications about tickets related to your projects should appear +- How you want notifications to appear. There are five options: + - No notifications + - All notifications + - `nodescription`: All notifications with the title of the ticket, but not its description + - `nocomments`: No notifications of comments on tickets + - `createclose`: Just notifications of ticket creation and resolution +- Specify who can use the `addme` command -- committers, members of your PMC only, ASF Members only... See also "Jira-related functions", below. @@ -37,22 +37,22 @@ To have Qbot active in a project's private channel, once it is available in your In Slack, there are three ways to talk to Qbot: - - Anywhere in the ASF workspace, type `/qbot` and the command you want to give it. If it is a command which you do not have permission to use where you currently are in Slack, the command will fail. - - In a channel where Qbot is present, type `qbot` without the slash, and the command. - - In the Slack interface, there is a general menu bar at the far left. The next column is the menu bar for the ASF workspace. Below the list of your contacts and channels, there is a section for `Apps`. Qbot appears there. - - Click that entry to see a display with three tabs. - - Select the `Messages` tab. - - Write your command to Qbot without `/` or 'qbot` at the start. +- Anywhere in the ASF workspace, type `/qbot` and the command you want to give it. If it is a command which you do not have permission to use where you currently are in Slack, the command will fail. +- In a channel where Qbot is present, type `qbot` without the slash, and the command. +- In the Slack interface, there is a general menu bar at the far left. The next column is the menu bar for the ASF workspace. Below the list of your contacts and channels, there is a section for `Apps`. Qbot appears there. + - Click that entry to see a display with three tabs. + - Select the `Messages` tab. + - Write your command to Qbot without `/` or 'qbot` at the start. ## Qbot commands **Note** we are expanding Qbot's reach, and this list will expand to match its capabilities. - - `help` - You see a list of the available commands: `qbot help`. +- `help` - You see a list of the available commands: `qbot help`. ### Adding yourself to a private channel - - `addme`- Add yourself to a private channel. (Without Qbot, you have to ask someone already in the channel to add you.) You can make the command from anywhere in the ASF workspace. The syntax is `/qbot addme `. +- `addme`- Add yourself to a private channel. (Without Qbot, you have to ask someone already in the channel to add you.) You can make the command from anywhere in the ASF workspace. The syntax is `/qbot addme `. ### Jira-related functions @@ -60,40 +60,40 @@ In Slack, there are three ways to talk to Qbot: **List Jira tickets for a project** - - List all the project's tickets, regardless of status: - - basic syntax: `qbot tickets project:` - - display the tickets that match a keyword search: `qbot tickets project: ` - - List the project's unassigned tickets: - - basic syntax: `qbot tickets unassigned:` - - display the project's unassigneed tickets that match a keyword search: `qbot tickets unassigned: ` +- List all the project's tickets, regardless of status: + - basic syntax: `qbot tickets project:` + - display the tickets that match a keyword search: `qbot tickets project: ` +- List the project's unassigned tickets: + - basic syntax: `qbot tickets unassigned:` + - display the project's unassigneed tickets that match a keyword search: `qbot tickets unassigned: ` **Find specific Jira tickets** - - Find tickets using Jira Query Language (JQL) - - syntax: `qbot tickets jql:` - - Find tickets using a keyword search - - syntax: `qbot tickets ` +- Find tickets using Jira Query Language (JQL) + - syntax: `qbot tickets jql:` +- Find tickets using a keyword search + - syntax: `qbot tickets ` *For keyword searches, separate multiple keywords with spaces.* ### Fun stuff - - `flip` - Qbot flips a coin and tells you whether it came up heads or tails: `/qbot flip`. +- `flip` - Qbot flips a coin and tells you whether it came up heads or tails: `/qbot flip`. - - `lauren` - Lauren works in the (fictional) Human Resources Department at The ASF. You can summon Lauren in any channel in which Qbot is active by typing her name three times in three consecutive posts (the way characters can summon a demon in the movie "Beetlejuice"). **Note** Lauren inhabits a parallel world to ours, one in which The ASF has a physical office with many employees who come in to work each day. Her statements may not bear too much relevance to the world you inhabit. You can also use the following commands to get Lauren's input: - - `lauren announce`: Lauren shares a significant (in Lauren's opinion) announcement. - - `lauren benefit`: Lauren reveals an employee benefit. - - `lauren complaint`: Lauren discusses a recent HR complaint with you. - - `lauren policy`: Lauren reminds you of a corporation policy. - - `roll` - If you send the command without furthr parameters (`qbot roll`), Qbot rolls one six-sided die and reports the result. - - You can roll up to ten dice at a time, and each die can have up to 100 sides or 'pips'.The syntax for a basic dice roll is `qbot roll NdP`, where `N` is the number of dice (up to 10) and `P` is the number of surfaces each die has (up to 100): `qbot roll 8d12`. - - In a role-playing game such as Dungeons and Dragons, when your character gets in trouble you may be able to try a **saving roll** to, well, save them from disaster. The syntax to see if Qbot can help in your current crisis is `qbot roll saving`. - - `shanty` - Qbot shares a verse of a sea shanty. The syntax is `qbot shanty`. +- `lauren` - Lauren works in the (fictional) Human Resources Department at The ASF. You can summon Lauren in any channel in which Qbot is active by typing her name three times in three consecutive posts (the way characters can summon a demon in the movie "Beetlejuice"). **Note** Lauren inhabits a parallel world to ours, one in which The ASF has a physical office with many employees who come in to work each day. Her statements may not bear too much relevance to the world you inhabit. You can also use the following commands to get Lauren's input: + - `lauren announce`: Lauren shares a significant (in Lauren's opinion) announcement. + - `lauren benefit`: Lauren reveals an employee benefit. + - `lauren complaint`: Lauren discusses a recent HR complaint with you. + - `lauren policy`: Lauren reminds you of a corporation policy. +- `roll` - If you send the command without furthr parameters (`qbot roll`), Qbot rolls one six-sided die and reports the result. + - You can roll up to ten dice at a time, and each die can have up to 100 sides or 'pips'.The syntax for a basic dice roll is `qbot roll NdP`, where `N` is the number of dice (up to 10) and `P` is the number of surfaces each die has (up to 100): `qbot roll 8d12`. + - In a role-playing game such as Dungeons and Dragons, when your character gets in trouble you may be able to try a **saving roll** to, well, save them from disaster. The syntax to see if Qbot can help in your current crisis is `qbot roll saving`. +- `shanty` - Qbot shares a verse of a sea shanty. The syntax is `qbot shanty`. _Note: the following two commands are in 'alpha' development and may not work as expected. If you would like to use them in huddles in your project's Slack spaces, please let us know (see 'Requesting features', below)._ - - `q` - This command starts a "Q & A" queue in a huddle in your current channel, and makes you the administrator. Such a function can be useful if you anticipate participants submitting a large number of questions. The syntax is `qbot q start`. - - `queue` - Performs the same function as `q`. The syntax is `qbot queue start`. +- `q` - This command starts a "Q & A" queue in a huddle in your current channel, and makes you the administrator. Such a function can be useful if you anticipate participants submitting a large number of questions. The syntax is `qbot q start`. +- `queue` - Performs the same function as `q`. The syntax is `qbot queue start`. ## Requesting features diff --git a/content/pages/release-distribution.md b/content/pages/release-distribution.md index dd3f51fb2..f24b8bfab 100644 --- a/content/pages/release-distribution.md +++ b/content/pages/release-distribution.md @@ -27,10 +27,10 @@ This policy governs how Apache Top Level Projects (TLPs) distribute releases of

Release distribution channels

- - The Apache Software Foundation's official channel for distribution of current Apache software releases to the general public is `downloads.apache.org/`. This directory provides access for current releases to the ASF content distribution network (CDN), through which most users download releases. - - The public may also obtain Apache software from downstream channels (rpm, deb, homebrew, etc.) which redistribute our releases in original or derived form. The vast majority of such downstream channels operate independently of Apache. - - Infra maintains a number of developer-only channels which facilitate distribution of unreleased software to consenting members of a development community. - - All historical Apache releases are available from `archive.apache.org`. +- The Apache Software Foundation's official channel for distribution of current Apache software releases to the general public is `downloads.apache.org/`. This directory provides access for current releases to the ASF content distribution network (CDN), through which most users download releases. +- The public may also obtain Apache software from downstream channels (rpm, deb, homebrew, etc.) which redistribute our releases in original or derived form. The vast majority of such downstream channels operate independently of Apache. +- Infra maintains a number of developer-only channels which facilitate distribution of unreleased software to consenting members of a development community. +- All historical Apache releases are available from `archive.apache.org`.

Release distribution directory

@@ -48,11 +48,11 @@ The Policy specifies that TLPs may distribute binary packages, provided by the p Projects **must** upload all official releases to the official distribution channel, `downloads.apache.org/`. Content suitable for the official distribution channel includes: - - Official releases - - PMC-approved artifacts, compiled code anyone can download and install - - Cryptographic signatures and checksums - - The KEYS file - - README, CHANGES and similar documents describing distributed content +- Official releases +- PMC-approved artifacts, compiled code anyone can download and install +- Cryptographic signatures and checksums +- The KEYS file +- README, CHANGES and similar documents describing distributed content If an Apache PMC wishes to publish additional materials through the official distribution channel and there is any question about the suitability of the materials, the PMC **must** consult with the ASF Board before publishing. @@ -60,10 +60,10 @@ If an Apache PMC wishes to publish additional materials through the official dis Unreleased materials, in original or derived form, - - **may** be distributed to consenting members of a project's development community - - **must not** be advertised to anyone outside of the project development community - - **must not** be distributed through `www.apache.org/dist` or `downloads.apache.org` - - **must not** be distributed through channels which encourage use by anyone outside the project development community +- **may** be distributed to consenting members of a project's development community +- **must not** be advertised to anyone outside of the project development community +- **must not** be distributed through `www.apache.org/dist` or `downloads.apache.org` +- **must not** be distributed through channels which encourage use by anyone outside the project development community

Recommended and maximum sizes of release artifacts

@@ -75,52 +75,52 @@ See the release signing page For every artifact distributed to the public through Apache channels, the PMC - - **must** supply a valid OpenPGP-compatible ASCII-armored detached signature file. - - **must** supply at least one checksum file. - - **should** supply a SHA-256 and/or SHA-512 checksum file. - - **SHOULD NOT** supply a MD5 or SHA-1 checksum file because these are deprecated. +- **must** supply a valid OpenPGP-compatible ASCII-armored detached signature file. +- **must** supply at least one checksum file. +- **should** supply a SHA-256 and/or SHA-512 checksum file. +- **SHOULD NOT** supply a MD5 or SHA-1 checksum file because these are deprecated. For new releases, PMCs **must** supply SHA-256 and/or SHA-512 and **should not** supply MD5 or SHA-1. You do not need to change existing releases. You **must** form the names of individual signature and checksum files by adding to the name of the artifact the appropriate suffix: - - `.asc` for a (ASCII-armored) PGP signature - - `.sha256` for an SHA-256 checksum - - `.sha512` for an SHA-512 checksum +- `.asc` for a (ASCII-armored) PGP signature +- `.sha256` for an SHA-256 checksum +- `.sha512` for an SHA-512 checksum Noted for completeness that this specification also applies to **deprecated** file types: - - `.md5` for an MD5 checksum - - `.sha1` for an SHA-1 checksum +- `.md5` for an MD5 checksum +- `.sha1` for an SHA-1 checksum Regarding signature and checksum files: - - Legacy suffix `.sha` **should not be** be used and `.sha` files **should not** be provided. - - Binary PGP signature `.sig` files **must not** be provided. - - `.mds` files (containing multiple checksums) **may** be provided for individual files as long as the included checksums comply with the above requirements. - - Signature and checksum files for verifying distributed artifacts **should not** be provided, unless named as indicated above. +- Legacy suffix `.sha` **should not be** be used and `.sha` files **should not** be provided. +- Binary PGP signature `.sig` files **must not** be provided. +- `.mds` files (containing multiple checksums) **may** be provided for individual files as long as the included checksums comply with the above requirements. +- Signature and checksum files for verifying distributed artifacts **should not** be provided, unless named as indicated above. Regarding KEYS files: - - Projects **must** publish a KEYS file in their distribution directory which contains all public keys used to sign artifacts. - - Signing keys used at Apache **must** be published in the KEYS file and **should** be made available through the global public keyserver network. Signing keys **should** be linked into a strong web of trust. - - Signing keys for new artifacts **must** be RSA and at least 2048 bit. New keys **should** be 4096 bit RSA. Signatures **should** be cryptographically strong. - - Private keys **must not** be stored on any ASF machine. Likewise, signatures for releases **must not** be created on ASF machines. - - You **must** revoke and replace compromised signing keys immediately. +- Projects **must** publish a KEYS file in their distribution directory which contains all public keys used to sign artifacts. +- Signing keys used at Apache **must** be published in the KEYS file and **should** be made available through the global public keyserver network. Signing keys **should** be linked into a strong web of trust. +- Signing keys for new artifacts **must** be RSA and at least 2048 bit. New keys **should** be 4096 bit RSA. Signatures **should** be cryptographically strong. +- Private keys **must not** be stored on any ASF machine. Likewise, signatures for releases **must not** be created on ASF machines. +- You **must** revoke and replace compromised signing keys immediately. - - Website documentation for any Apache product **must** provide public download links where interested parties may obtain current official source releases and accompanying cryptographic files. - - Links to artifacts **must not** reference the main Apache web site. They **must** use the [standard procedure](release-download-pages.html) to make downloads available through the content distribution system. - - All links to checksums, detached signatures and public keys for current releases **must** reference `downloads.apache.org/` using `https://`. - - Legacy links to `https://[www.]apache.org/dist/...` still work, but new links should use `downloads.apache.org`. - - Older release checksums are on `archive.apache.org`, and you **may** also link to them. - - All releases, including old releases, are archived automatically. You **may** link from your PMC's download page to archived older releases for community convenience. +- Website documentation for any Apache product **must** provide public download links where interested parties may obtain current official source releases and accompanying cryptographic files. +- Links to artifacts **must not** reference the main Apache web site. They **must** use the [standard procedure](release-download-pages.html) to make downloads available through the content distribution system. +- All links to checksums, detached signatures and public keys for current releases **must** reference `downloads.apache.org/` using `https://`. + - Legacy links to `https://[www.]apache.org/dist/...` still work, but new links should use `downloads.apache.org`. + - Older release checksums are on `archive.apache.org`, and you **may** also link to them. +- All releases, including old releases, are archived automatically. You **may** link from your PMC's download page to archived older releases for community convenience.

Releases are archived

- - All releases are archived automatically on `archive.apache.org`. This automated process generally adds releases to the archive about a day after they first appear on `downloads.apache.org/`. - - Each project's distribution directory **should** contain the latest release in each branch that is currently under development. When development ceases on a version branch, the PMC **should** remove links to releases of that branch from their download directory. +- All releases are archived automatically on `archive.apache.org`. This automated process generally adds releases to the archive about a day after they first appear on `downloads.apache.org/`. +- Each project's distribution directory **should** contain the latest release in each branch that is currently under development. When development ceases on a version branch, the PMC **should** remove links to releases of that branch from their download directory.

Using Maven for releases

diff --git a/content/pages/release-download-pages.md b/content/pages/release-download-pages.md index c1d956b11..d24fac97d 100644 --- a/content/pages/release-download-pages.md +++ b/content/pages/release-download-pages.md @@ -7,8 +7,8 @@ Your project's release download page is where people can download your product's Review - - the policy on [release distribution](release-distribution.html) if you are unsure of the best way to use the project download page - - guidelines on [signing releases](release-signing.html) +- the policy on [release distribution](release-distribution.html) if you are unsure of the best way to use the project download page +- guidelines on [signing releases](release-signing.html) ## Contents @@ -23,32 +23,32 @@ Review - - Your project's download page can only link to release artifacts that your PMC has approved. - - Do not link directly to `dist.apache.org`. - - The download page **must** include a link to the source distribution. It **may** include links to binary distributions. - - Use **closer.lua**, the standard mechanism to distribute Apache downloads. See below for details. - - All links to checksums, detached signatures and public keys **must** reference the Apache Distribution Directory (downloads.apache.org) and use `https://` (SSL). For example: `https://downloads.apache.org/httpd/KEYS`. - - All releases are automatically archived. You may continue to link to recent releases, as well as the latest one, from the download page, as a convenience for the user community. You **should** remove links to older releases that you no longer support. - - Remove all official pre-releases (e.g. milestones, alphas, betas) in a timely fashion once the project releases the final or GA version. +- Your project's download page can only link to release artifacts that your PMC has approved. +- Do not link directly to `dist.apache.org`. +- The download page **must** include a link to the source distribution. It **may** include links to binary distributions. +- Use **closer.lua**, the standard mechanism to distribute Apache downloads. See below for details. +- All links to checksums, detached signatures and public keys **must** reference the Apache Distribution Directory (downloads.apache.org) and use `https://` (SSL). For example: `https://downloads.apache.org/httpd/KEYS`. +- All releases are automatically archived. You may continue to link to recent releases, as well as the latest one, from the download page, as a convenience for the user community. You **should** remove links to older releases that you no longer support. +- Remove all official pre-releases (e.g. milestones, alphas, betas) in a timely fashion once the project releases the final or GA version.

Your Apache project's download page

Your Apache project's download page: - - **must** have at least one link to the current release. This link **must** use the `closer.lua` utility. For example: `https://www.apache.org/dyn/closer.lua/PROJECT/VERSION/SOURCE-RELEASE`. (Note: the `mirrors.cgi` and `closer.cgi` scripts have been deprecated. Calls to them redirect to `closer.lua`.) - - **must** have a link to the checksum for the current release. These links **must** use direct links to the Apache distribution server. For example: `https://downloads.apache.org/PROJECT/VERSION/CHECKSUM`. - - **must** have a link to the KEYS file for your project on the Apache distribution server. For example: `https://downloads.apache.org/PROJECT/KEYS`. - - **must** have a link to the signature file for each release. See the [release signing](release-signing.html) page for more information. - - **should** have instructions on how to verify downloads. For this you can include a link to the Apache documentation on verification. - - **must not** include a download link to the top-level `closer.lua` utility (e.g. `http://www.apache.org/dyn/closer.lua/PROJECT`). +- **must** have at least one link to the current release. This link **must** use the `closer.lua` utility. For example: `https://www.apache.org/dyn/closer.lua/PROJECT/VERSION/SOURCE-RELEASE`. (Note: the `mirrors.cgi` and `closer.cgi` scripts have been deprecated. Calls to them redirect to `closer.lua`.) +- **must** have a link to the checksum for the current release. These links **must** use direct links to the Apache distribution server. For example: `https://downloads.apache.org/PROJECT/VERSION/CHECKSUM`. +- **must** have a link to the KEYS file for your project on the Apache distribution server. For example: `https://downloads.apache.org/PROJECT/KEYS`. +- **must** have a link to the signature file for each release. See the [release signing](release-signing.html) page for more information. +- **should** have instructions on how to verify downloads. For this you can include a link to the Apache documentation on verification. +- **must not** include a download link to the top-level `closer.lua` utility (e.g. `http://www.apache.org/dyn/closer.lua/PROJECT`).

Current and older releases

Do **not** keep software distributions on your project's website. Move them to one of these two sites: - - **Current public releases** appear on `downloads.apache.org/`. Place current, official releases that the PMC has approved for end-users on the main public release site. Make all changes at `https://dist.apache.org/repos/dist/release/`. +- **Current public releases** appear on `downloads.apache.org/`. Place current, official releases that the PMC has approved for end-users on the main public release site. Make all changes at `https://dist.apache.org/repos/dist/release/`. - - **Older releases** that you no longer recommend to the general public still appear on `archive.apache.org/dist/`. This site automatically contains all the content that has ever appeared on `downloads.apache.org/`. It is rarely necessary to touch this site, except during a reorganization. Once your project no longer recommends public use of a particular release, delete it from `downloads.apache.org/dist/` by removing it from https://dist.apache.org/repos/dist/release/, and removing the link to it from your download page. It remain on the archive site. +- **Older releases** that you no longer recommend to the general public still appear on `archive.apache.org/dist/`. This site automatically contains all the content that has ever appeared on `downloads.apache.org/`. It is rarely necessary to touch this site, except during a reorganization. Once your project no longer recommends public use of a particular release, delete it from `downloads.apache.org/dist/` by removing it from https://dist.apache.org/repos/dist/release/, and removing the link to it from your download page. It remain on the archive site. To remove an old release from the release area, use a command of the form: @@ -62,15 +62,15 @@ Apache project download pages **must** use a closer.lua script. You'll find belo There are two options: - - The closer.lua download script is quick to set up. The project documentation links to it (rather than integrating it). - - A project-specific script, which in the end calls `closer.lua` integrated with a page created in the normal way for the project and uses the project's standard document look and feel. This option takes more time to set up. +- The closer.lua download script is quick to set up. The project documentation links to it (rather than integrating it). +- A project-specific script, which in the end calls `closer.lua` integrated with a page created in the normal way for the project and uses the project's standard document look and feel. This option takes more time to set up.

Generic closer.lua download script

The starting point for using the generic `closer.lua` script is a download page in your project's standard documentation which describes the releases. To use the generic script: - - Alter the page so the download link points to `closer.lua`. - - Pass in the relative path from the distribution root to the artifact as a parameter. +- Alter the page so the download link points to `closer.lua`. +- Pass in the relative path from the distribution root to the artifact as a parameter. If the artifact is `foo-5.5.1.zip` and it is located in `bar/foo` relative to `downloads.apache.org`, then the link `http://www.apache.org/dyn/closer.lua/bar/foo/foo-5.5.1.zip` provides the link for downloading. @@ -90,8 +90,8 @@ This URI takes the path to the page as an input and passes it to `closer.lua`. W There is no requirement to name the script `download.cgi` and the download release page `download.html`, but the name of the script **must** correspond to the name of the download page. For example: - - `release.cgi` and `release.html` will work - - `download.cgi` and `release.html` will **not** work +- `release.cgi` and `release.html` will work +- `download.cgi` and `release.html` will **not** work There are a number of elements that a good project download page should contain. See the content to generate that page here. Alternately, you can get inspiration from the [default download template](https://github.com/apache/infrastructure-p6/blob/production/modules/closer_cgi/files/closer.html) that will be used when no custom HTML template exists for a project. diff --git a/content/pages/release-integrity-primer.md b/content/pages/release-integrity-primer.md index 3188e1a30..7d87bdf02 100644 --- a/content/pages/release-integrity-primer.md +++ b/content/pages/release-integrity-primer.md @@ -20,8 +20,8 @@ Each reported error has an accompanying error code (`CHKxx`). The code will help In case of an invalid or missing signature for a release artifact, the project MUST choose one of the following actions: - - Remove the artifact(s) - - Re-assert that the artifact is valid, sign and upload the correct .asc signature file (and fix any missing/invalid checksum files) +- Remove the artifact(s) +- Re-assert that the artifact is valid, sign and upload the correct .asc signature file (and fix any missing/invalid checksum files) In either case, the project MUST inform the ASF Infrastructure and Security Team at `private@infra.apache.org` and `security@apache.org` of their action, with clear evidence that the action diff --git a/content/pages/release-publishing.md b/content/pages/release-publishing.md index 4f238aa5e..9ca923b00 100644 --- a/content/pages/release-publishing.md +++ b/content/pages/release-publishing.md @@ -9,17 +9,17 @@ Every Apache Software Foundation project software release must meet requirements ## Contents ## - - An Apache release - - The release manager - - A valid release package - - Signing release artifacts - - Voting whether to approve the release - - Distribution - - Uploading packages - - Normal distribution on the Apache downloads site - - Maven distribution - - Release distribution availability schedule - - FAQs +- An Apache release +- The release manager +- A valid release package +- Signing release artifacts +- Voting whether to approve the release +- Distribution + - Uploading packages + - Normal distribution on the Apache downloads site + - Maven distribution +- Release distribution availability schedule +- FAQs

An Apache release

@@ -79,9 +79,9 @@ Infra maintains the Apache release distribution infrastructure, which has three

Uploading packages

- - Upload development packages and snapshots to `https://dist.apache.org/repos/dist/dev/$project/` - - Upload release packages to `https://dist.apache.org/repos/dist/release/$project/`. If your project uses a Subversion repository, you can use `svn mv` from the `dev` folder. - - Incubator projects can find their dev/release folder inside their incubator directory. +- Upload development packages and snapshots to `https://dist.apache.org/repos/dist/dev/$project/` +- Upload release packages to `https://dist.apache.org/repos/dist/release/$project/`. If your project uses a Subversion repository, you can use `svn mv` from the `dev` folder. +- Incubator projects can find their dev/release folder inside their incubator directory.

Normal distribution on the Apache downloads site

@@ -89,19 +89,19 @@ See the [Release Distribution Policy](release-distribution.html) for specific te Each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at `https://dist.apache.org/repos/dist/`. Once a release vote passes, the release manager adds the release artifacts (plus signature and hash files) to this location. Each project is responsible for the structure of its directory. [PyPubSub](pypubsub.html) pushes the contents of these directories to `https://downloads.apache.org/`. **Note** only store the most recent version of each supported release here. - - **Do not** use the SVN directories under `https://dist.apache.org/repos/dist/` to link to product releases. Projects must use the ASF release system. See [Release Download Pages](release-download-pages.html) for further details. +- **Do not** use the SVN directories under `https://dist.apache.org/repos/dist/` to link to product releases. Projects must use the ASF release system. See [Release Download Pages](release-download-pages.html) for further details. - - A signature (`.asc`) can become invalid because the signing key is revoked or has expired. Make sure all current signatures for your project in `downloads.apache.org/` are valid. +- A signature (`.asc`) can become invalid because the signing key is revoked or has expired. Make sure all current signatures for your project in `downloads.apache.org/` are valid. - - Hash, signature and KEYS files are excluded from the public release: +- Hash, signature and KEYS files are excluded from the public release: `*.md5 *.sha *.sha1 *.sha256 *.sha512 *.asc *.sig KEYS *.mds MD5SUM SHA*SUM` - - **Do not** publish `.md5` files because MD5 is broken. - - **Do not** publish `.sig` files. Make sure your `.asc`s are plain-text files. - - The download page should use `HTTPS:` rather than plain `HTTP:` for linking to KEYS, sigs and hashes (for example: `https://downloads.apache.org/httpd/KEYS`). +- **Do not** publish `.md5` files because MD5 is broken. +- **Do not** publish `.sig` files. Make sure your `.asc`s are plain-text files. +- The download page should use `HTTPS:` rather than plain `HTTP:` for linking to KEYS, sigs and hashes (for example: `https://downloads.apache.org/httpd/KEYS`). - - In addition to the checksum files required in the [Release Distribution Policy](release-distribution.html), the project can provide an `MD5SUM` or `SHA*SUM`. `MD5SUM` and `SHA*SUM` must look like the output of `md5sum(1)`: lines containing a checksum, followed by a filename ; use only plain file names (no slashes). Do not use any other file names for such files. +- In addition to the checksum files required in the [Release Distribution Policy](release-distribution.html), the project can provide an `MD5SUM` or `SHA*SUM`. `MD5SUM` and `SHA*SUM` must look like the output of `md5sum(1)`: lines containing a checksum, followed by a filename ; use only plain file names (no slashes). Do not use any other file names for such files. If the release directory does not yet exist, please create a Jira ticket for INFRA with the required information (see the [contact](contact.html) page). @@ -134,6 +134,6 @@ As a rule of thumb, projects should currently:

FAQs

- - **How do I archive an old release?** `downloads.apache.org` is automatically archived every four hours. Therefore, a copy of every official release exists in the archives. Just delete the copy of the release that is in your project's dist directory. Remember to update any links from the download page related to that release. +- **How do I archive an old release?** `downloads.apache.org` is automatically archived every four hours. Therefore, a copy of every official release exists in the archives. Just delete the copy of the release that is in your project's dist directory. Remember to update any links from the download page related to that release. **Note**: Projects using the [Apache Trusted Releases](atr.html) (ATR) platform can configure their ATR project so that archiving of older releases is automated. diff --git a/content/pages/release-signing.md b/content/pages/release-signing.md index f5f2ae901..993607759 100644 --- a/content/pages/release-signing.md +++ b/content/pages/release-signing.md @@ -26,14 +26,14 @@ This document is informative and does not constitute policy. ### FAQs from those downloading releases - - What does verifying a signature mean? - - How can I check the integrity of a release? - - What is the difference between secure hardware and trusted hardware? - - What does 'Public key not found' mean when verifying a signature? - - What is a trusted key? - - What is the difference between a valid signature from an untrusted key and an invalid signature from a trusted key? - - What is a public key fingerprint? - - Can I mark a key as locally trusted? +- What does verifying a signature mean? +- How can I check the integrity of a release? +- What is the difference between secure hardware and trusted hardware? +- What does 'Public key not found' mean when verifying a signature? +- What is a trusted key? +- What is the difference between a valid signature from an untrusted key and an invalid signature from a trusted key? +- What is a public key fingerprint? +- Can I mark a key as locally trusted? ## For release managers @@ -45,9 +45,9 @@ Recent research has revealed weaknesses in SHA-1, and thus in the DSA and 1024 b The impact of this weakness on Apache can be mitigated by action now. What needs to be done is a little involved, so we have provided complete instructions. - - Committers without a code signing key should read this document and follow these [instructions](openpgp.html#generate-key). - - Committers with a DSA key or an RSA key of length less than 2048 bits should generate a new key for signing releases. The original key does not need to be revoked yet. Follow this [guide](key-transition.html). - - Committers with RSA keys of length 2048 or more do not need to generate a new key yet. They should reconfigure their client to avoid the weakness by following these [instructions](openpgp.html#sha1) and wait for the next major OpenPGP revision. +- Committers without a code signing key should read this document and follow these [instructions](openpgp.html#generate-key). +- Committers with a DSA key or an RSA key of length less than 2048 bits should generate a new key for signing releases. The original key does not need to be revoked yet. Follow this [guide](key-transition.html). +- Committers with RSA keys of length 2048 or more do not need to generate a new key yet. They should reconfigure their client to avoid the weakness by following these [instructions](openpgp.html#sha1) and wait for the next major OpenPGP revision. How to find the length of your key is described [here](#key-length-how-to). @@ -55,13 +55,13 @@ How to find the length of your key is described [here](#key-length-how-to). Every artifact distributed by the Apache Software Foundation **must** be accompanied by one file containing an OpenPGP-compatible ASCII armored detached signature and another file containing a SHA-256 or SHA-512 checksum. - - New releases **must** use SHA-256 and/or SHA-512 checksums. - - MD5 and SHA-1 are **deprecated** and **should not** be supplied for new releases. Existing releases do not need to change. +- New releases **must** use SHA-256 and/or SHA-512 checksums. +- MD5 and SHA-1 are **deprecated** and **should not** be supplied for new releases. Existing releases do not need to change. Form the names of these files by adding to the name of the artifact the following suffixes: - - the signature by suffixing `.asc` - - the checksum by suffixing `.sha256` or `.sha512` (as appropriate) +- the signature by suffixing `.asc` +- the checksum by suffixing `.sha256` or `.sha512` (as appropriate) Release managers **must not** store private keys used to sign Apache releases on ASF hardware. @@ -71,21 +71,21 @@ See the release distribution p A signature allows anyone to verify that a file is identical to the one your project's release manager created. Since your project's release has a signature: - - users can make sure that what they received has not been modified in any way, either accidentally via a faulty transmission channel, or intentionally (with or without malicious intent). - - the Apache infrastructure team can verify the identity of a file. +- users can make sure that what they received has not been modified in any way, either accidentally via a faulty transmission channel, or intentionally (with or without malicious intent). +- the Apache infrastructure team can verify the identity of a file. OpenPGP signatures confer the usual advantages of digital signatures: authentication, integrity and non-repudiation. MD5 and SHA checksums only provide the integrity part as they are not encrypted.

Security checklist

- - Protect your private key - - Choose a good passphrase - - Opt for a reasonably long key length +- Protect your private key +- Choose a good passphrase +- Opt for a reasonably long key length

Signing basics

- - Signatures should be ASCII armored and detached. - - You should export your public key and append the result to the appropriate KEYS file(s). +- Signatures should be ASCII armored and detached. +- You should export your public key and append the result to the appropriate KEYS file(s).

How do I sign a release?

@@ -95,9 +95,9 @@ Create a OpenPGP compatible ASCII armored de It is - - an OpenPGP compatible - - ASCII armored - - detached signature +- an OpenPGP compatible +- ASCII armored +- detached signature To create one using GNU Privacy Guard for file `foo.tar.gz`, type: @@ -226,11 +226,11 @@ SHA512 is the strongest well-studied, widely-used cryptographic hash. It is ther The exact mechanics are application-dependent. For GnuPG (recommended): - - Follow the strong key generation instructions - - Decide on the right key length - - Configure the tool to avoid SHA-1 - - Choose a good passphrase - - Use the recommended id and comment +- Follow the strong key generation instructions +- Decide on the right key length +- Configure the tool to avoid SHA-1 +- Choose a good passphrase +- Use the recommended id and comment

The OpenPGP User-ID to use for your code-signing key

@@ -255,8 +255,8 @@ The major public key servers synchronize their records regularly so you only nee There are two common ways to upload a key to a public key server: - - Most key servers let you upload exports through their websites - - Use automatic facilities built into most OpenPGP implementations +- Most key servers let you upload exports through their websites +- Use automatic facilities built into most OpenPGP implementations For example, using GNU Privacy Guard, send the key with ID B1313DE2 to the default public key server by: @@ -425,11 +425,11 @@ To practice using OpenPGP, use separate environments. each with a different prac For example, using GNU Privacy Guard: - - (First time only)Create a directory to contain the keyring - - Open the shell to be configured to use this keyring - - Change to the directory - - (First time only) `$ mkdir -m 700 .gnupg` - - Set up the environment: `export GNUPGHOME=.gnupg` +- (First time only)Create a directory to contain the keyring +- Open the shell to be configured to use this keyring +- Change to the directory +- (First time only) `$ mkdir -m 700 .gnupg` +- Set up the environment: `export GNUPGHOME=.gnupg`

What is a Web Of Trust?

@@ -454,8 +454,8 @@ A key signing party is a meeting organised to allow the exchange of public keys You can link into the Apache web of trust by meeting other Apache committers face-to-face and exchanging public keys: - - Apache committers organizes key signing parties at each ApacheCon. - - If you are not able to attend ApacheCon, or it will not happen for several months, consider organising a face-to-face meeting of local committers. +- Apache committers organizes key signing parties at each ApacheCon. +- If you are not able to attend ApacheCon, or it will not happen for several months, consider organising a face-to-face meeting of local committers. Subscribe to the `party` list and when you visit a new city, see if committers want to meet up. @@ -467,10 +467,10 @@ A public key is for verifying signatures and encrypting messages; a private key Anyone who possesses a copy of a private key used to sign releases can create doctored releases with valid signatures. If this person intends harm then the consequences could be serious indeed. It is therefore very important to keep the private key secret. - - Only sign releases on a secure machine. - - Keep your signing application fully patched. - - Keep the key file safe and secret. - - Choose a good passphrase. +- Only sign releases on a secure machine. +- Keep your signing application fully patched. +- Keep the key file safe and secret. +- Choose a good passphrase.

How safe does the private key need to be?

@@ -510,10 +510,10 @@ You should generate a revocation certificate for each public key you use. Store Each revocation certificate has a type specifying a general (machine readable) reason for the revocation: - - No reason specified - - Key has been compromised - - Key is superseded - - Key is no longer used +- No reason specified +- Key has been compromised +- Key is superseded +- Key is no longer used Create certificates to cover the first two cases. Note that if a key is lost or can no longer be accessed (due to media failure or some other reason), assume that the key has been potentially compromised. Print copies of the revocation certificates and store them safely to guard against media failure. @@ -548,10 +548,10 @@ Store each revocation certificate securely and separately from the key it revoke If a key has been compromised, distribute its revocation certificate to those using the key. This process is a mirror of the process by which you distributred the original key. - - Inform the Apache infrastructure team by a post containing the revocation certificate. - - Update the KEYS files containing the original key with the revocation certificate. - - Upload the revocation certificate to the major keyserver networks. - - Post an announcement to the appropriate lists with the revocation certificate attached. +- Inform the Apache infrastructure team by a post containing the revocation certificate. +- Update the KEYS files containing the original key with the revocation certificate. +- Upload the revocation certificate to the major keyserver networks. +- Post an announcement to the appropriate lists with the revocation certificate attached.

The difference between deleting and revoking a key

@@ -635,10 +635,10 @@ to import the public keys.

OpenPGP uses a web of trust. The owner of a public key who trusts the identity of a second key may mark this key as trusted by signing it. This has several major effects: - - In future, no untrusted key warning appears when a valid signature for +- In future, no untrusted key warning appears when a valid signature for this key is verified. - - Keys the owner of the key trusts may also become trusted. In other words, if the owner of a key whose identity you trust confirms the identity of a key, that key may be automatically trusted. This behavior is typically configurable. - - The next time you export your key, those who trust your key may start to trust the identity of the trusted key. +- Keys the owner of the key trusts may also become trusted. In other words, if the owner of a key whose identity you trust confirms the identity of a key, that key may be automatically trusted. This behavior is typically configurable. +- The next time you export your key, those who trust your key may start to trust the identity of the trusted key. The transitive nature of the web of trust places a responsibility on the owner to verify the identity of the owner of those keys marked as trusted. @@ -715,11 +715,11 @@ The project must request a signing key through an Infra Jira ticket, and Infra w There are many other excellent resources on signing releases, but these make a good start: - - The Guide to using GnuPG at Apache - - The Apache Key Transition Guide - - RFC 1321 MD5 message-digest algorithm - - RFC 2440 OpenPGP message format - - The GNU Privacy Guard project documentation - - An introduction to PGP public key cryptography - - Applied Cryptography by Bruce Schneier - - Windows-centric PGP FAQ by Tom McCune

+- The Guide to using GnuPG at Apache +- The Apache Key Transition Guide +- RFC 1321 MD5 message-digest algorithm +- RFC 2440 OpenPGP message format +- The GNU Privacy Guard project documentation +- An introduction to PGP public key cryptography +- Applied Cryptography by Bruce Schneier +- Windows-centric PGP FAQ by Tom McCune

diff --git a/content/pages/repository-faq.md b/content/pages/repository-faq.md index 71aeef57a..4c75b06ad 100644 --- a/content/pages/repository-faq.md +++ b/content/pages/repository-faq.md @@ -11,8 +11,8 @@ The ASF maintains internal snapshot and release Maven repositories at Maven Central and snapshots are available here: http://repository.apache.org/snapshots/. diff --git a/content/pages/request-bug-tracker.md b/content/pages/request-bug-tracker.md index fa8a2514f..a28e82537 100644 --- a/content/pages/request-bug-tracker.md +++ b/content/pages/request-bug-tracker.md @@ -10,10 +10,10 @@ The ASF recommends these options for tracking issues and feature requests: Infra itself uses Jira, so to request a Jira instance for your project, create a Jira ticket. Set the issue type to 'New Jira Project' and provide the necessary details: - - A list of committers with access to modify/close tickets - - A list of committers who will act as Jira administrators - - A notification scheme (to which email address do JIRA notifications go?) - - A name and description for the Jira instance +* A list of committers with access to modify/close tickets +* A list of committers who will act as Jira administrators +* A notification scheme (to which email address do JIRA notifications go?) +* A name and description for the Jira instance ### Response @@ -42,8 +42,8 @@ If your project switches from Jira to GitHub for receiving issue reports and fea Once GitHub issue tracking is active for the project, open what will probably be your final Jira ticket for Infra, requesting Infra to: - - Change all existing Jira tickets for the project to read-only - - Remove the project name from the drop-down list of projects that a person can choose from when creating a Jira ticket. +* Change all existing Jira tickets for the project to read-only +* Remove the project name from the drop-down list of projects that a person can choose from when creating a Jira ticket. Infra will let you know when this has been completed. diff --git a/content/pages/responsetime.md b/content/pages/responsetime.md index 16e55de9c..ff49893b2 100644 --- a/content/pages/responsetime.md +++ b/content/pages/responsetime.md @@ -21,49 +21,49 @@ Here is how we triage issue reports and service requests submitted as Jira ticke A time-sensitive issue that is hindering a project's basic functions. - - **Goal**: 24 hours to respond, 3 days (72h) to resolve. Weekend hours count against this goal. - - **Example**: Web site has been defaced and we just sent out a press release. +- **Goal**: 24 hours to respond, 3 days (72h) to resolve. Weekend hours count against this goal. +- **Example**: Web site has been defaced and we just sent out a press release. #### Critical A time-sensitive issue that causes disruption for a project, but is not hindering basic functionality. - - **Goal**: 36 hours to respond, 4 days (96h) to resolve. Weekend hours count against this goal. - - **Example**: We just called a new release, but SVN is not allowing us to upload or move the artifacts. +- **Goal**: 36 hours to respond, 4 days (96h) to resolve. Weekend hours count against this goal. +- **Example**: We just called a new release, but SVN is not allowing us to upload or move the artifacts. #### Major This is the default Jira issue priority. It fits a large issue that Infra should resolve quickly, but is not time-sensitive or related to basic project functions. This includes requesting new resources. - - **Goal**: 2 days (48h) to respond, 5 days (120h) to resolve. Weekends do not count against this goal. - - **Examples**: - - Set up a new podling. - - Add a git repository. - - Set up py/svn/git-pubsub. +- **Goal**: 2 days (48h) to respond, 5 days (120h) to resolve. Weekends do not count against this goal. +- **Examples**: + - Set up a new podling. + - Add a git repository. + - Set up py/svn/git-pubsub. #### Minor An issue that Infra should resolve within a reasonable time, is not time-sensitive and is not critical to a project's basic functionas or ongoing daily business. - - **Goal**: 3 days (72h) to respond, 2 weeks (336h) to resolve. Weekends do not count against this goal. - - **Examples**: - - Retire a project's resources. - - Fix a JavaScript error on a web site. - - Add GitHub integration for a repository. - - Refine Jira settings for a project. +- **Goal**: 3 days (72h) to respond, 2 weeks (336h) to resolve. Weekends do not count against this goal. +- **Examples**: + - Retire a project's resources. + - Fix a JavaScript error on a web site. + - Add GitHub integration for a repository. + - Refine Jira settings for a project. #### Trivial A task that Infra should resolve, but that has minimal or no time constraints. - - **Goal**: 3 days (72h) to respond, 4 weeks (672h) to resolve. Weekends do not count against this goal. - - **Example**: Fix copyright year on a web site. +- **Goal**: 3 days (72h) to respond, 4 weeks (672h) to resolve. Weekends do not count against this goal. +- **Example**: Fix copyright year on a web site. ### Notes - - Response time is counted as first reply (from someone else) or assignment. - - Tickets marked as `Planned Work` do not have a response-time goal. - - Tickets marked as `Waiting for user` have no response time goal until the user responds. - - Weekends do not count toward response time for all tickets except those marked `Blocker` or `Critical`. - - Tickets only appear in response statistics once resolved or if exceeding the goal for their category. - - Ticket velocity (user engagement and interaction) is important. +- Response time is counted as first reply (from someone else) or assignment. +- Tickets marked as `Planned Work` do not have a response-time goal. +- Tickets marked as `Waiting for user` have no response time goal until the user responds. +- Weekends do not count toward response time for all tickets except those marked `Blocker` or `Critical`. +- Tickets only appear in response statistics once resolved or if exceeding the goal for their category. +- Ticket velocity (user engagement and interaction) is important. diff --git a/content/pages/roundtable.md b/content/pages/roundtable.md index e8aeec629..f8a001872 100644 --- a/content/pages/roundtable.md +++ b/content/pages/roundtable.md @@ -3,9 +3,9 @@ license: https://www.apache.org/licenses/LICENSE-2.0 To provide a space for conversations on issues related to the ASF's infrastructure, Infra holds a monthly roundtable of free-flowing discussion. - - The roundtable takes place on the first Wednesday of most months for an hour, usually starting at 1700 UTC, in a huddle on Slack's `#roundtable` channel in the ASF workspace. - - Infra announces in advance the general topic for each month's meeting. - - The roundtables are available to anyone who can access the ASF workspace on Slack: basically, committers and Members. +- The roundtable takes place on the first Wednesday of most months for an hour, usually starting at 1700 UTC, in a huddle on Slack's `#roundtable` channel in the ASF workspace. +- Infra announces in advance the general topic for each month's meeting. +- The roundtables are available to anyone who can access the ASF workspace on Slack: basically, committers and Members. During the roundtable, people can either **speak or type** their comments. If you follow the chat screen only, with no audio, you will miss significant parts of the meeting. Turning on a webcam, on the other hand, is optional. @@ -27,10 +27,10 @@ When you are in the channel, you can share messages with others as a sort of pre ### What happens in the roundtable - - An Infra team member normally opens the meeting with a short presentation related to the advertised topic, and then throws the floor open to discussion. - - If you are using a microphone, please mute your mic when not speaking, to cut down on ambient noise. - - To contribute to the discussion, either type your message in the huddle thread (not the main channel thread) or unmute and start speaking. We will all try to practice good meeting manners, which include not talking over others. - - If time permits, we can discuss any other urgent, Infra-related topic that is on your mind. +- An Infra team member normally opens the meeting with a short presentation related to the advertised topic, and then throws the floor open to discussion. +- If you are using a microphone, please mute your mic when not speaking, to cut down on ambient noise. +- To contribute to the discussion, either type your message in the huddle thread (not the main channel thread) or unmute and start speaking. We will all try to practice good meeting manners, which include not talking over others. +- If time permits, we can discuss any other urgent, Infra-related topic that is on your mind. ### To leave the roundtable diff --git a/content/pages/sensitive_info.md b/content/pages/sensitive_info.md index 3297e8135..e875cd81b 100644 --- a/content/pages/sensitive_info.md +++ b/content/pages/sensitive_info.md @@ -3,10 +3,10 @@ license: https://www.apache.org/licenses/LICENSE-2.0 It is sometimes necessary for you to share sensitive information with the Infrastructure team so that Infra can resolve a problem: - - Your LDAP credentials no longer work - - Your project's code has a security vulnerability - - You need to share personally-identifying information (PII), yours or someone else's - - You need to pass an organization secret to Infra to be stored in GitHub +- Your LDAP credentials no longer work +- Your project's code has a security vulnerability +- You need to share personally-identifying information (PII), yours or someone else's +- You need to pass an organization secret to Infra to be stored in GitHub **Do not** share such information on an ASF Slack channel, a public email thread, as a comment on a Jira ticket, or as a GitHub issue. diff --git a/content/pages/services.md b/content/pages/services.md index a21dff891..bd8f17fb8 100644 --- a/content/pages/services.md +++ b/content/pages/services.md @@ -5,69 +5,69 @@ license: https://www.apache.org/licenses/LICENSE-2.0 Infra maintains a wide range of tools for PMCs, project committers, and the Apache Board and its committees to use. Parts of our toolkit are only available to people who have specific duties or roles. Others, like the monitoring tools that show the status of various parts of the Apache infrastructure, are available to everyone. - - Services for Top-Level Projects (TLPs) - - Websites - - Email - - ASF self-service platform - - ASF account management - - Getting notices of infrastructure events - - LDAP-enabled services - - Services for incubating projects (podlings) - - Tools for ASF projects - - Version control - - Issue tracking and feature requests - - Integrating your repository with Jira tickets - - Source repository publisher/subscriber services - - Build services - - GitHub Actions - - Product naming - - Code signing - - Code quality - - Code distribution - - Virtual servers - - Online voting - - **Visual Studio**: The ASF has a presence in the Visual Studio Marketplace. Several projects have posted extensions there to make it easier for their developers to work in VS on their product's code. Projects that would like to add their extensions to the Marketplace should make the request to Infra in a Jira ticket. - - Other tools - - DNS - - URL shortener - - Machine list +- Services for Top-Level Projects (TLPs) + - Websites + - Email + - ASF self-service platform + - ASF account management + - Getting notices of infrastructure events + - LDAP-enabled services +- Services for incubating projects (podlings) +- Tools for ASF projects + - Version control + - Issue tracking and feature requests + - Integrating your repository with Jira tickets + - Source repository publisher/subscriber services + - Build services + - GitHub Actions + - Product naming + - Code signing + - Code quality + - Code distribution + - Virtual servers + - Online voting + - **Visual Studio**: The ASF has a presence in the Visual Studio Marketplace. Several projects have posted extensions there to make it easier for their developers to work in VS on their product's code. Projects that would like to add their extensions to the Marketplace should make the request to Infra in a Jira ticket. +- Other tools + - DNS + - URL shortener + - Machine list

Services for Top-Level Projects (TLPs)

Websites

- - `www.apache.org` is the main ASF website. - - ASF project websites. - - ASF project website sources - - An index of all ASF projects (if they have set up a DOAP). - - Any ASF project can use the [ASF-Pelican template](asf-pelican.html) as the basis for their project website. - - Details about individual ASF Committers. - - Notes about committers' personal web spaces. - - The Apache Project Website Checker periodically reviews all TLP websites and reports whether they comply with Apache's policies for TLP websites. +- `www.apache.org` is the main ASF website. +- ASF project websites. +- ASF project website sources +- An index of all ASF projects (if they have set up a DOAP). +- Any ASF project can use the [ASF-Pelican template](asf-pelican.html) as the basis for their project website. +- Details about individual ASF Committers. +- Notes about committers' personal web spaces. +- The Apache Project Website Checker periodically reviews all TLP websites and reports whether they comply with Apache's policies for TLP websites.

Email

- - Watch out for [phishing](phishing.html) - - [Emailing tips](contrib-email-tips.html) - - All requests for new email lists should go through the self-serve system. Remember not to mark a list as private if you want it publicly archived. - - Email server - QMail/QSMTPD - - email lists - EZMLM - - Searchable email list archives. ASF Members have full access to private emails; PMC members have access to their PMC's archives only. - - Review [details about searching and creating emails](email_lists.html) in `lists.apache.org`. - - Spam control - Spamfilter + SpamAssassin - - Email forwarding: See id.apache.org - - Infra maintains and uses a series of email lists, some of which are open to committers. +- Watch out for [phishing](phishing.html) +- [Emailing tips](contrib-email-tips.html) +- All requests for new email lists should go through the self-serve system. Remember not to mark a list as private if you want it publicly archived. +- Email server - QMail/QSMTPD +- email lists - EZMLM +- Searchable email list archives. ASF Members have full access to private emails; PMC members have access to their PMC's archives only. + - Review [details about searching and creating emails](email_lists.html) in `lists.apache.org`. +- Spam control - Spamfilter + SpamAssassin +- Email forwarding: See id.apache.org +- Infra maintains and uses a series of email lists, some of which are open to committers.

ASF self-service platform

One of Infra's goals is to empower ASF members, PMCs, and committers to do much of what they need to do without having to request help from Infra. The Self-Service Platform, for example, provides a number of handy tools that **people who have an Apache email address** (basically, project committers, PMC members, and ASF Members) can use to: - * Create a Jira or Confluence project, Git repository, or email list (PMC Chairs and Infra members). - * Edit your ASF identity or update your ASF password. If you are updating your password, you need access to the email account associated with your Apache account. A reset key is only valid for 15 minutes, so be sure to use it as soon as it arrives. - * Synchronize Git repositories. - * Use the OTP Calculator to generate one-time passwords for the OTP or S/Key one-time-password systems (generally, PMC members). - * Archive a Confluence Wiki space and make it read-only. +- Create a Jira or Confluence project, Git repository, or email list (PMC Chairs and Infra members). +- Edit your ASF identity or update your ASF password. If you are updating your password, you need access to the email account associated with your Apache account. A reset key is only valid for 15 minutes, so be sure to use it as soon as it arrives. +- Synchronize Git repositories. +- Use the OTP Calculator to generate one-time passwords for the OTP or S/Key one-time-password systems (generally, PMC members). +- Archive a Confluence Wiki space and make it read-only. People who are not part of the ASF community but wish to file a Jira ticket about an ASF project's product can use the platform to request a Jira account. @@ -87,8 +87,8 @@ Infra supports many ASF Tools for ASF projects @@ -110,22 +110,22 @@ Infra supports an array of tools and services to help projects develop and suppo Apache provides, and Infra maintains, [code repositories](version-control.html) that Apache projects can use to keep their project code safe, accessible to team members, and under version control. - - Information about [using Git](git-primer.html) - - [Read-only Git mirrors of SVN codebases](git.html) - - [Writable Git repositories](project-repo-policy.html) - - [Apache and GitHub](apache-github.html) - - [Access roles for GitHub repositories](github-roles.html) +- Information about [using Git](git-primer.html) + - [Read-only Git mirrors of SVN codebases](git.html) + - [Writable Git repositories](project-repo-policy.html) + - [Apache and GitHub](apache-github.html) + - [Access roles for GitHub repositories](github-roles.html) - - Information about [using Subversion](svn-basics.html) - - Subversion (SVN) repositories - - ViewVC (Browser interface to the main SVN repository) +- Information about [using Subversion](svn-basics.html) + - Subversion (SVN) repositories + - ViewVC (Browser interface to the main SVN repository)

Issue tracking and feature requests

The ASF supports these options for tracking issues and feature requests: -* Jira (Note: [qbot](qbot.html) is a tool that can integrate Jira notifications with a project's channel in the `the-asf` [Slack](slack.html) workspace.) -* The GitHub issue tracking feature +- Jira (Note: [qbot](qbot.html) is a tool that can integrate Jira notifications with a project's channel in the `the-asf` [Slack](slack.html) workspace.) +- The GitHub issue tracking feature For historical reasons, some projects use Bugzilla. We continue to support Bugzilla, but will not set it up for projects that do not already use it. @@ -143,7 +143,7 @@ Infra can activate a [Subversion and Git integration with Jira tickets](svngit2j

Source repository publisher/subscriber services

- - [PyPubSub](pypubsub.html) +- [PyPubSub](pypubsub.html)

Build services

@@ -151,8 +151,8 @@ Apache supports and models continuous integration and continuous deployment, or Other tools to consider: -* Travis CI -* AppVeyor +- Travis CI +- AppVeyor

GitHub Actions

@@ -178,13 +178,13 @@ That response has a cost: by default, a `groups` block applies only to **version Here are ways you and your PMC can help mitigate this issue: - - **Optimize PR workflows**: Run full test suites periodically on main merges or via scheduled "canary" builds rather than on every PR. Use `paths:` filters in GitHub Actions YAML, write custom scripts to determine dynamic build matrix outputs, or utilize tools like Apache Yetus or [Develocity](gradle.html) (develocity.apache.org) for predictive test selection. Contact Infra via a Jira ticket or by email to `users@infra` for advice on the best approach for your project. - - **Review workflows for anomalies**: Check for deprecated labels like `macos-13`, which cause workers to hang in "waiting for runner" status and artificially inflate queue sizes. Also, review custom parallelism settings that might block valid jobs. The [GitHub Actions Policy](github-actions-policy.html) requires a job concurrency level of 20 or less per workflow, and recommends staying at or below 15. - - **Group your dependency updates**: An ungrouped Dependabot configuration opens one pull request and one full CI run per dependency. Combine them with `groups`, and add `applies-to: security-updates` so that security fixes are batched as well instead of arriving as a stream of single-dependency PRs. See [grouping security updates](dependabot.html#group-security-updates) for the configuration. - - **Pin first-party actions to a major version tag**: The [GitHub Actions Policy](github-actions-policy.html) requires a specific git hash only for **external** actions; actions in the `apache/*`, `github/*` and `actions/*` namespaces may be used without that restriction. Pinning those to a major version tag rather than to a hash lets a patch or minor release arrive without a pull request, which removes a large share of the Dependabot traffic a project sees. External actions still **MUST** be pinned to a specific git hash. - - **Reuse workflows across repositories**: A project with several repositories can keep its shared CI in reusable workflows in one repository and call them from the rest. An action or dependency update is then reviewed and tested once rather than once per repository, which cuts both the number of Dependabot pull requests and the CI runs behind them. - - **Use lightweight runners**: For small, short jobs, consider using `runs-on: ubuntu-slim`. These provide 1 vCPU, 5GB RAM, no Docker engine, and a 15-minute hard limit. They churn much more quickly during peak times, allowing you to bypass the standard `ubuntu-latest` queue while freeing up capacity for others. - - **Explore self-hosted runners**: Speak with the Infra team about setting up project-specific [self-hosted runners](self-hosted-runners.html), particularly if you have targeted donations or cloud credits available. +- **Optimize PR workflows**: Run full test suites periodically on main merges or via scheduled "canary" builds rather than on every PR. Use `paths:` filters in GitHub Actions YAML, write custom scripts to determine dynamic build matrix outputs, or utilize tools like Apache Yetus or [Develocity](gradle.html) (develocity.apache.org) for predictive test selection. Contact Infra via a Jira ticket or by email to `users@infra` for advice on the best approach for your project. +- **Review workflows for anomalies**: Check for deprecated labels like `macos-13`, which cause workers to hang in "waiting for runner" status and artificially inflate queue sizes. Also, review custom parallelism settings that might block valid jobs. The [GitHub Actions Policy](github-actions-policy.html) requires a job concurrency level of 20 or less per workflow, and recommends staying at or below 15. +- **Group your dependency updates**: An ungrouped Dependabot configuration opens one pull request and one full CI run per dependency. Combine them with `groups`, and add `applies-to: security-updates` so that security fixes are batched as well instead of arriving as a stream of single-dependency PRs. See [grouping security updates](dependabot.html#group-security-updates) for the configuration. +- **Pin first-party actions to a major version tag**: The [GitHub Actions Policy](github-actions-policy.html) requires a specific git hash only for **external** actions; actions in the `apache/*`, `github/*` and `actions/*` namespaces may be used without that restriction. Pinning those to a major version tag rather than to a hash lets a patch or minor release arrive without a pull request, which removes a large share of the Dependabot traffic a project sees. External actions still **MUST** be pinned to a specific git hash. +- **Reuse workflows across repositories**: A project with several repositories can keep its shared CI in reusable workflows in one repository and call them from the rest. An action or dependency update is then reviewed and tested once rather than once per repository, which cuts both the number of Dependabot pull requests and the CI runs behind them. +- **Use lightweight runners**: For small, short jobs, consider using `runs-on: ubuntu-slim`. These provide 1 vCPU, 5GB RAM, no Docker engine, and a 15-minute hard limit. They churn much more quickly during peak times, allowing you to bypass the standard `ubuntu-latest` queue while freeing up capacity for others. +- **Explore self-hosted runners**: Speak with the Infra team about setting up project-specific [self-hosted runners](self-hosted-runners.html), particularly if you have targeted donations or cloud credits available.

Product naming

@@ -192,11 +192,11 @@ See [guidance for choosing a product name](project-names.html)

Code signing

- - Code signing service - - Requesting access to the [code signing service](code-signing-access.html) - - [Using the code signing service](code-signing-use.html) - - [Cryptography with OpenPGP](openpgp.html) - - For distribution via the Apple App Store +- Code signing service + - Requesting access to the [code signing service](code-signing-access.html) + - [Using the code signing service](code-signing-use.html) +- [Cryptography with OpenPGP](openpgp.html) +- For distribution via the Apple App Store

Code quality

@@ -212,17 +212,17 @@ Use the ASF Nexus Repos

Distributions

- - Current distributions - - Historical distribution archives - - [Rsync for distribution mirrors](how-to-mirror.html) - - Nexus +- Current distributions +- Historical distribution archives +- [Rsync for distribution mirrors](how-to-mirror.html) +- Nexus

Virtual servers

Infra can provide Ubuntu virtual machines for projects. See: - - [Virtual machine policy](vm-policy.html) - - [Process for requesting a vm](vm-for-project.html) +- [Virtual machine policy](vm-policy.html) +- [Process for requesting a vm](vm-for-project.html)

Use of nightlies.a.o

diff --git a/content/pages/slack.md b/content/pages/slack.md index a4645dc9b..228da1d7d 100644 --- a/content/pages/slack.md +++ b/content/pages/slack.md @@ -32,8 +32,8 @@ Infra has disabled the option that would let you provide a member invite link to Slack has two account types: - - **Member**: has full access to all Slack's features, including inviting others to join the workspace. - - **Guest**: has limited access inside Slack and can only access the channel(s) they are invited to join. +- **Member**: has full access to all Slack's features, including inviting others to join the workspace. +- **Guest**: has limited access inside Slack and can only access the channel(s) they are invited to join. Slack has a list of permissions for these account types. @@ -44,15 +44,15 @@ Both the ASF and Slack use the term 'member', but in different ways. The Slack u For the Apache Software Foundation: - An ASF Member is a "person who was nominated by current members and elected due to merit for the evolution and progress of the foundation." - - A PMC member is a "developer or a committer that was elected" to the PMC. +- A PMC member is a "developer or a committer that was elected" to the PMC. ## Joining project channels Once you are part of the ASF workspace as a member or a multi-channel guest, you can join any public channels you wish to. - - At the top of your list of channels in the Slack app, click the **+** icon. - - Use the _Browse channels_ option to display a list of open channels in the workspace; or enter text in the search field. - - Select any channel to add it to your channel list. +- At the top of your list of channels in the Slack app, click the **+** icon. +- Use the _Browse channels_ option to display a list of open channels in the workspace; or enter text in the search field. +- Select any channel to add it to your channel list. Some ASF channels are **private** or **locked**, and do not appear on the list of channels you can join. Someone who is already in the channel has to invite you to join such a channel. @@ -64,9 +64,9 @@ It is good manners to send a hello message to a channel you join, possibly with Before setting up a new project channel, search the ASF workspace to make sure it does not already exist. If it does not, any member of the workspace can add the channel. - - At the top of your list of channels in the Slack app, click the **+** icon - - Use the _Browse channels_ option to see if the channel you are thinking of already exists. If you can't find it, click _Create Channel_ at the top of the channels list; or use the _Create a channel_ option under the + icon. - - After you provide a name for the channel, you can set it as **public**, so any member of the ASF can see and join it, or **private**, as noted above. People can only join a private channel by invitation. +- At the top of your list of channels in the Slack app, click the **+** icon +- Use the _Browse channels_ option to see if the channel you are thinking of already exists. If you can't find it, click _Create Channel_ at the top of the channels list; or use the _Create a channel_ option under the + icon. +- After you provide a name for the channel, you can set it as **public**, so any member of the ASF can see and join it, or **private**, as noted above. People can only join a private channel by invitation. If you _do_ add a channel for your project, make sure you tell the PMC, committers, and other stakeholders about it so they can find and make use of it. diff --git a/content/pages/stats.md b/content/pages/stats.md index f59e15b52..1d068c4ca 100644 --- a/content/pages/stats.md +++ b/content/pages/stats.md @@ -1,14 +1,14 @@ Title: Status pages license: https://www.apache.org/licenses/LICENSE-2.0 - - See what services are running well and which are reporting issues on the Status page. If a problem is showing here, Infra has already received an alert about it. +- See what services are running well and which are reporting issues on the Status page. If a problem is showing here, Infra has already received an alert about it. - - Our ASF Infrastructure Reporting Dashboard has a variety of live reports, including uptime statistics, website source scans, and more. +- Our ASF Infrastructure Reporting Dashboard has a variety of live reports, including uptime statistics, website source scans, and more. - - To view download stats for your project, visit the download stats page. +- To view download stats for your project, visit the download stats page. - - Review how Infra triages incident reports and service requests, and their [response-time goals](responsetime.html). +- Review how Infra triages incident reports and service requests, and their [response-time goals](responsetime.html). - - The Reporter wizard provides a wide range of interesting information about Apache projects, and can help PMCs assemble their quarterly Board reports. +- The Reporter wizard provides a wide range of interesting information about Apache projects, and can help PMCs assemble their quarterly Board reports. - - Abuse and connectivity issues: ABC lets you check whether your IP address has been blocked for a violation of one of the ASF rules of use, such as more than a set number of pageviews per hour, and provides guidance about what you should to to get the IP address unblocked. +- Abuse and connectivity issues: ABC lets you check whether your IP address has been blocked for a violation of one of the ASF rules of use, such as more than a set number of pageviews per hour, and provides guidance about what you should to to get the IP address unblocked. diff --git a/content/pages/svn-basics.md b/content/pages/svn-basics.md index 0b3c5026e..d11b7a22f 100644 --- a/content/pages/svn-basics.md +++ b/content/pages/svn-basics.md @@ -7,10 +7,10 @@ Apache committers have write access to the Apache Subversion repository so they If you are looking for a stable release of a project's source code, you should download it from the distribution directory. Only download directly from the SVN repository if you want to be on the *bleeding-edge* of the development effort. The code contained there may fail to work, and may even eat your hard drive. - - Accessing the Subversion repository - - Configuring the Subversion client - - SSL server certificate - - Frequently asked questions +- Accessing the Subversion repository +- Configuring the Subversion client +- SSL server certificate +- Frequently asked questions

Accessing the Subversion repository

diff --git a/content/pages/svngit2jira.md b/content/pages/svngit2jira.md index 62ca0e9ad..febe6eaf8 100644 --- a/content/pages/svngit2jira.md +++ b/content/pages/svngit2jira.md @@ -20,12 +20,12 @@ projects have a trigger set so that it only updates a ticket if the first sente To enable the service for your project, create an Infra Jira ticket. Include this information: - - The name of the project. - - Has the PMC agreed to use this? (Make sure of this before requesting the feature, as it does tend to add quite a lot of new information to a Jira ticket.) - - What Jira name does your project use? - - Does the project use Git or Subversion? - - How would you like commits to trigger an update of a JIRA ticket. This can be anything from the standard catch-all FOO-1234 trigger to more specific rules you thought of yourself. - - If you are using Git, are there any specific branches you'd like the service to ignore? +- The name of the project. +- Has the PMC agreed to use this? (Make sure of this before requesting the feature, as it does tend to add quite a lot of new information to a Jira ticket.) +- What Jira name does your project use? +- Does the project use Git or Subversion? +- How would you like commits to trigger an update of a JIRA ticket. This can be anything from the standard catch-all FOO-1234 trigger to more specific rules you thought of yourself. +- If you are using Git, are there any specific branches you'd like the service to ignore?

Source code

diff --git a/content/pages/user-ssh.md b/content/pages/user-ssh.md index d5db3a940..694d7452e 100644 --- a/content/pages/user-ssh.md +++ b/content/pages/user-ssh.md @@ -7,12 +7,12 @@ Remember to keep your client up to date with security patches. Pay close attenti ## Contents ## - - Using OpenSSH to connect to Apache - - Configuring OpenSSH to use SSH2 (*nix) - - Debugging an OpenSSH client connection - - Troubleshooting - - FAQs - - More information +- Using OpenSSH to connect to Apache +- Configuring OpenSSH to use SSH2 (*nix) +- Debugging an OpenSSH client connection +- Troubleshooting +- FAQs +- More information

Using OpenSSH to connect to Apache

@@ -47,9 +47,9 @@ ssh -v -l yourApacheID some-project-server.apache.org

Troubleshooting

- - If you encounter a problem with SSH and you are not running the most modern stable release of the client software you are connecting with, upgrade and retry. - - Configure the client to use SSH2 where possible so the connection to Apache uses the SSH2 protocol. This protocol is more secure and lets you use an interactive keyboard (type in password) or PKI. If you must use SSH1, you will need to use PKI. - - Read the section on debugging SSH and try to diagnose the problem. +- If you encounter a problem with SSH and you are not running the most modern stable release of the client software you are connecting with, upgrade and retry. +- Configure the client to use SSH2 where possible so the connection to Apache uses the SSH2 protocol. This protocol is more secure and lets you use an interactive keyboard (type in password) or PKI. If you must use SSH1, you will need to use PKI. +- Read the section on debugging SSH and try to diagnose the problem.

Some common problems

@@ -119,4 +119,4 @@ A class of attacks where the attacker masquerades as the server to the client an

More information

- - Identity theft +- Identity theft diff --git a/content/pages/version-control.md b/content/pages/version-control.md index e8c22e786..044762831 100644 --- a/content/pages/version-control.md +++ b/content/pages/version-control.md @@ -5,18 +5,18 @@ Apache project contributors are in countries all around the world. To help them ## Contents ## - - In general - - Git repositories - - Creating repositories - - .asf.yaml for Git repositories - - SVN repositories - - Command-line SVN access - - Committing code through the command line - - Configuring the SVN client - - SVN SSL server certificate - - Typical SVN error messages - - SVN FAQs - - Migrating an SVN code repository to Git +- In general +- Git repositories + - Creating repositories + - .asf.yaml for Git repositories +- SVN repositories + - Command-line SVN access + - Committing code through the command line + - Configuring the SVN client + - SVN SSL server certificate + - Typical SVN error messages + - SVN FAQs +- Migrating an SVN code repository to Git

In general

@@ -34,8 +34,8 @@ How-to guides, documentation, and a list of projects using Git for revision cont Many Git users manage their source code through one of these tools: -* GitBox -* GitHub +- GitBox +- GitHub Some projects began using [read-only-mirrors](git.html) of SVN repositories when Apache's support for Git was limited. This is no longer necessary. [Writable Git](project-repo-policy.html) repositories are available to all projects. @@ -45,10 +45,10 @@ Apache projects can have as many **public** Git repositories as their product de Some projects require a **private** Git repository, for reasons like: - - Developing security patches. - - Preparing the quarterly Bzoard reports when it is necessary to include information in a `` section of the report. - - Maintaining the details of legal contracts, Memorandums of Understanding (MOUs) and similar arrangements with third parties. PMCs can enter into such arrangements if they are directly required for the development of the project's product or products. - - Keeping information that should not be public. +- Developing security patches. +- Preparing the quarterly Bzoard reports when it is necessary to include information in a `` section of the report. +- Maintaining the details of legal contracts, Memorandums of Understanding (MOUs) and similar arrangements with third parties. PMCs can enter into such arrangements if they are directly required for the development of the project's product or products. +- Keeping information that should not be public. Each PMC can have **one** private Git repository. Open a Jira ticket for Infra to request one, explaining the reasons the project needs it. @@ -58,9 +58,9 @@ Each PMC can have **one** private Git repository. Open a Jira ticket for Infra t Projects can also place `.asf.yaml` in the root of a repository to control: -- notification settings -- GitHub settings -- pelican builds +- notification settings +- GitHub settings +- pelican builds Read [the .asf.yaml primer](asf-yaml.html) to learn more. diff --git a/content/pages/vm-for-project.md b/content/pages/vm-for-project.md index 6361804ac..1c952816f 100644 --- a/content/pages/vm-for-project.md +++ b/content/pages/vm-for-project.md @@ -7,12 +7,12 @@ Infra maintains hosts in different computer centers around the world to run virt ### Contents ### - - Requesting a virtual machine - - Deploying the virtual machine - - Project maintainers - - Obtaining SSH keys - - General maintenance - - Cautions +- Requesting a virtual machine +- Deploying the virtual machine +- Project maintainers +- Obtaining SSH keys +- General maintenance +- Cautions

Requesting a virtual machine

@@ -99,23 +99,23 @@ Tip: You can review the files of some other committer: `ls -al ~mymentor; cat ~m There are no mandatory rules, but here are some suggestions: - - Keep all changes in Git/Puppet. See: `https://github.com/apache/infrastructure-p6` - - If you do not have karma, please create PRs in a branch against our GitHub repository. - - Keep all application data in `/x1` if possible. - - Update Puppet with all extra installed packages. - - See `https://github.com/apache/infrastructure-p6/tree/production/modules//manifests/init.pp` - - See also the Git workflow for an Infrastructure Puppet repository. +- Keep all changes in Git/Puppet. See: `https://github.com/apache/infrastructure-p6` + - If you do not have karma, please create PRs in a branch against our GitHub repository. + - Keep all application data in `/x1` if possible. +- Update Puppet with all extra installed packages. + - See `https://github.com/apache/infrastructure-p6/tree/production/modules//manifests/init.pp` + - See also the Git workflow for an Infrastructure Puppet repository. See also [Managing virtual machines](vm-management.html)

Cautions

- - Do not try to change items controlled by puppet, such as: - - iptables - - sshd - - ldap - - /root/bin - - anything else relevant for security - - As sudoer you are expected to know what you do, and are expected to clear any problems you create. +- Do not try to change items controlled by puppet, such as: + - iptables + - sshd + - ldap + - /root/bin + - anything else relevant for security +- As sudoer you are expected to know what you do, and are expected to clear any problems you create. Before doing something, you are always welcome to join #asfinfra on Slack and ask about it. diff --git a/content/pages/vm-management.md b/content/pages/vm-management.md index 023cb3490..c7a80ae0f 100644 --- a/content/pages/vm-management.md +++ b/content/pages/vm-management.md @@ -13,39 +13,39 @@ When an Apache project requests a VM, it identifies three project committers who Infra is responsible for most VM high-level management tasks: - - Starting the VM. - - Shutting down the VM (projects can halt, but not re-start the VM as it requires access to the VM provider). If you have stopped your VM, you will need to ask Infra to re-start it. - - Cloning the VM. This occurs very rarely. - - Migrating to a new VM. Infra creates the new VM and can assist with puppet (re)config as needed. +- Starting the VM. +- Shutting down the VM (projects can halt, but not re-start the VM as it requires access to the VM provider). If you have stopped your VM, you will need to ask Infra to re-start it. +- Cloning the VM. This occurs very rarely. +- Migrating to a new VM. Infra creates the new VM and can assist with puppet (re)config as needed. ## Maintenance Your project is responsible for maintenance tasks like - - renewing or replacing expired letsencrypt certificates - - resolving disk space issues - - maintaining any software configured by the project - - addressing security issues in software configured by the project in a timely and appropriate manner - - replying to Infra and Security queries regarding the VM in a timely and appropriate manner +- renewing or replacing expired letsencrypt certificates +- resolving disk space issues +- maintaining any software configured by the project +- addressing security issues in software configured by the project in a timely and appropriate manner +- replying to Infra and Security queries regarding the VM in a timely and appropriate manner You do not need to worry about upgrading the base operating system or other packages Infra installed when setting up the VM. They receive upgrades automatically, and the system will be rebooted automatically when a security patch requires it. ## What Infra will do - - Create your VM upon request. Each project can have one VM. Make your case to vp-infra if you feel you absolutely need more than one. - - Configure the base operating system, install Infra configuration management (puppet) - - Add users to host ACL and sudoers as needed/requested by the PMC - - Back up the system (see [backup policy](backup-policy.html)) - - Apply operating system updates and security patches automatically - - Reboot the system with or without notice as Infra deems necessary - - Assist the project in defining Puppet configuration management where desired and appropriate +- Create your VM upon request. Each project can have one VM. Make your case to vp-infra if you feel you absolutely need more than one. +- Configure the base operating system, install Infra configuration management (puppet) +- Add users to host ACL and sudoers as needed/requested by the PMC +- Back up the system (see [backup policy](backup-policy.html)) +- Apply operating system updates and security patches automatically +- Reboot the system with or without notice as Infra deems necessary +- Assist the project in defining Puppet configuration management where desired and appropriate ## What Infra will not do - - Develop advanced software configurations for your project's workflow - - Fix or maintain software deployed by the project - - Develop advanced Puppet configuration automation for your project's deployments - - Provide access to ASF infrastructure build deployment secrets +- Develop advanced software configurations for your project's workflow +- Fix or maintain software deployed by the project +- Develop advanced Puppet configuration automation for your project's deployments +- Provide access to ASF infrastructure build deployment secrets ## When you get stuck diff --git a/content/pages/vm-policy.md b/content/pages/vm-policy.md index f4cba5751..5b0a7b315 100644 --- a/content/pages/vm-policy.md +++ b/content/pages/vm-policy.md @@ -12,5 +12,5 @@ Infra will maintain this VM via our existing configuration management tooling. T See also: - - the process to [request a VM for your project](vm-for-project.html) - - [Managing virtual machines](vm-management.html) +- the process to [request a VM for your project](vm-for-project.html) +- [Managing virtual machines](vm-management.html) From 76a6e30d3c2de3362d3787c7acf1a85c7fda3ca6 Mon Sep 17 00:00:00 2001 From: Justin Mclean Date: Fri, 16 Oct 2026 20:38:31 +1100 Subject: [PATCH 2/3] Label the language of code blocks in pages Turns MD040 back on and labels all 143 unlabelled code blocks. highlight.js now uses the label instead of guessing, and output and email text show as plain text. --- .markdownlint-cli2.yaml | 1 - content/blog/README.md | 4 +- content/blog/newsletter_02_25.md | 2 +- content/blog/newsletter_03_25.md | 2 +- content/blog/newsletter_04_26.md | 2 +- content/blog/newsletter_06_25.md | 2 +- content/pages/account-mgmt.md | 2 +- content/pages/asf-pelican-config.md | 8 +- content/pages/asf-pelican-data.md | 2 +- content/pages/asf-pelican-gettingstarted.md | 4 +- content/pages/asf-pelican-theme.md | 2 +- content/pages/asfyaml-mkdocs.md | 2 +- content/pages/crypto.md | 6 +- content/pages/git-primer.md | 16 ++-- content/pages/github-actions-secrets.md | 4 +- content/pages/how-to-mirror.md | 10 +-- content/pages/key-transition.md | 18 ++--- content/pages/licensing-howto.md | 4 +- content/pages/mailing-list-moderation.md | 24 +++--- content/pages/open-access-svn.md | 2 +- content/pages/openpgp.md | 82 ++++++++++----------- content/pages/patch.md | 2 +- content/pages/pelican-buildbot.md | 2 +- content/pages/project-site.md | 4 +- content/pages/publishing-maven-artifacts.md | 12 +-- content/pages/release-download-pages.md | 4 +- content/pages/release-signing.md | 44 +++++------ content/pages/request-bug-tracker.md | 2 +- content/pages/svn-basics.md | 8 +- content/pages/user-ssh.md | 6 +- content/pages/version-control.md | 2 +- content/pages/vm-for-project.md | 2 +- 32 files changed, 143 insertions(+), 144 deletions(-) diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index d7e22d00d..96c2d1706 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -25,7 +25,6 @@ config: MD034: false MD036: false MD038: false - MD040: false MD045: false MD046: false MD048: false diff --git a/content/blog/README.md b/content/blog/README.md index 87f078793..68e42bde7 100644 --- a/content/blog/README.md +++ b/content/blog/README.md @@ -36,7 +36,7 @@ Pelican supports these tags, which the Infra blog does not use: The first line of the file should have this metadata, at a minimum: -``` +```text layout: post title: THE ENTRY'S TITLE date: 2010-01-01 permalink: KEY WORDS FROM THE TITLE category CATEGORY ``` @@ -44,7 +44,7 @@ Note that the title does not need a period at its end. For better readability as you are editing, you can lay out the metadata using multiple lines: -``` +```yaml layout: post title: THE ENTRY'S TITLE date: 2010-01-01 diff --git a/content/blog/newsletter_02_25.md b/content/blog/newsletter_02_25.md index 18dbed80d..a954aa6f0 100644 --- a/content/blog/newsletter_02_25.md +++ b/content/blog/newsletter_02_25.md @@ -36,7 +36,7 @@ Other significant enhancements include: To opt in to the updated .asf.yaml, add this code to your existing .asf.yaml file: -``` +```yaml meta:   nextgen: true ``` diff --git a/content/blog/newsletter_03_25.md b/content/blog/newsletter_03_25.md index 0be926b94..115687842 100644 --- a/content/blog/newsletter_03_25.md +++ b/content/blog/newsletter_03_25.md @@ -30,7 +30,7 @@ GitHub Discussions are now managed entirely through .asf.yaml, and will default To enable Discussions, include these settings into the .asf.yaml file in your default branch: -``` +```yaml notifications: discussions: issues@foo.apache.org (use your own mailing list name here) ... diff --git a/content/blog/newsletter_04_26.md b/content/blog/newsletter_04_26.md index 708220cc7..b1ed808ef 100644 --- a/content/blog/newsletter_04_26.md +++ b/content/blog/newsletter_04_26.md @@ -51,7 +51,7 @@ Projects are seeing a large number of phishing attempts in Slack workspaces. The The project can assign the Triage (or collaborator) role to a user who is not a committer or ASF Member in the repository's `.asf.yaml` file with an entry like this: -``` +```yaml github: collaborators: - externalgithubuserhere diff --git a/content/blog/newsletter_06_25.md b/content/blog/newsletter_06_25.md index ba644730b..3308898f4 100644 --- a/content/blog/newsletter_06_25.md +++ b/content/blog/newsletter_06_25.md @@ -38,7 +38,7 @@ Due to a significant increase in abuse, largely driven by AI scraping, the ASF B Infra received this message from GitHiub: -``` +```text The Windows Server 2019 runner image will be fully unsupported by June 30, 2025. To raise awareness of the upcoming removal, we will temporarily fail jobs using Windows Server 2019. Builds that are scheduled to run during the brownout periods will fail. diff --git a/content/pages/account-mgmt.md b/content/pages/account-mgmt.md index a76b0e114..2ee063974 100644 --- a/content/pages/account-mgmt.md +++ b/content/pages/account-mgmt.md @@ -21,7 +21,7 @@ If you forgot your password, try... your `@apache.org` address (which forwards to your non-apache email account) a short-lived password reset link. The link may be encrypted to your PGP key. 1. decrypting the e-mail - one way to do this is to save the e-mail contents as a text file, e.g. `password.txt`. Open a shell command window, and run the following command: -``` +```text gpg -d password.txt ``` diff --git a/content/pages/asf-pelican-config.md b/content/pages/asf-pelican-config.md index 4475855f5..83b6d65d9 100644 --- a/content/pages/asf-pelican-config.md +++ b/content/pages/asf-pelican-config.md @@ -16,7 +16,7 @@ These are the sections to configure in `pelicanconf.yaml` for your website: ## Required -``` +```yaml site: name: Apache Template description: Provides a template for projects wishing to use the Pelican ASF static content system @@ -35,7 +35,7 @@ theme: theme/apache If you are using the standard plugins included in ASF Pelican, you can leave this section out. If you include it, your build will automatically include the `gfm` plugin. -``` +```yaml plugins: paths: - theme/plugins @@ -47,7 +47,7 @@ plugins: To configure four special features: -``` +```yaml setup: data: asfdata.yaml run: @@ -70,7 +70,7 @@ setup: The `asfgenid` plugin performs a number of fixups and enhancements. -``` +```yaml genid: unsafe: yes metadata: yes diff --git a/content/pages/asf-pelican-data.md b/content/pages/asf-pelican-data.md index 51a9c9a2e..b8c1a1a17 100644 --- a/content/pages/asf-pelican-data.md +++ b/content/pages/asf-pelican-data.md @@ -14,7 +14,7 @@ If your site includes the `asfdata.py` plugin, the Pelican site generator reads The `pelicanconf.yaml` file contains the following: -``` +```yaml setup: data: asfdata.yaml ``` diff --git a/content/pages/asf-pelican-gettingstarted.md b/content/pages/asf-pelican-gettingstarted.md index f7026a310..e204b2309 100644 --- a/content/pages/asf-pelican-gettingstarted.md +++ b/content/pages/asf-pelican-gettingstarted.md @@ -25,7 +25,7 @@ If you wish to try out the template: 4. Unzip `master.zip` and copy `infrastructure-website-master/*` to the root of your new repository. 5. Configure [.asf.yaml](asf-yaml.html). -``` +```yaml pelican: notify: EMAIL of a person on your team to receive error messages related to Pelican autobuild: preview/* @@ -85,7 +85,7 @@ Please let us know if you run into [issues](https://github.com/apache/template-s Earlier versions of this template made use of a `pelicanconf.py` configuration file. The current version uses `.asf.yaml` and `pelicanconf.yaml`, as noted above. We retain the earlier instruction for the projects using the earlier version of the template; however, any project starting with the template now should use the files and instructions noted above. -``` +```text Edit the `pelicanconf.py` configuration file: - Website specific diff --git a/content/pages/asf-pelican-theme.md b/content/pages/asf-pelican-theme.md index 6e2ae5780..a9e830f47 100644 --- a/content/pages/asf-pelican-theme.md +++ b/content/pages/asf-pelican-theme.md @@ -55,7 +55,7 @@ Manage Pelican settings in the bisnotice.xsl can generate the BIS notice for a product based on the XML data. For example, running it as: -``` +```text $ cd {SVNROOT}/infrastructure/site/trunk/ $ svn up $ cd content/licenses/exports/ @@ -71,7 +71,7 @@ will result in text output that looks like an email template for the PMC chair t There are also some sample script files in the top-level directory (site/trunk): `bisnotice.cmd` (Windows) and `bisnotice.sh` (Un*x). -``` +```text TO: crypt AT bis.doc.gov, enc AT nsa.gov, web_site AT bis.doc.gov @@ -101,7 +101,7 @@ NOTIFICATION: http://www.apache.org/licenses/exports/ Should the software qualify for the Section 742.15(b) exemption, place the following notice into each distribution's README file: -``` +```text This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of diff --git a/content/pages/git-primer.md b/content/pages/git-primer.md index dd223a294..c0d21e8de 100644 --- a/content/pages/git-primer.md +++ b/content/pages/git-primer.md @@ -46,7 +46,7 @@ Open a Jira ticket for Infra to request a private repository. The repository URLs are all of the form: -``` +```text https://gitbox.apache.org/repos/asf/reponame.git ``` @@ -70,14 +70,14 @@ For details on how .asf.yaml can help you manage your GitHub settings, see > ~/.netrc <Apache HTTP Server version 2.2 or later and use the following configuration for your web mirror to allow all the features of our download site to function optimally: -``` +```apache IndexOptions FancyIndexing NameWidth=* FoldersFirst ScanHTMLTitles DescriptionWidth=* HeaderName HEADER.html @@ -50,7 +50,7 @@ We only support rsync for Update your mirror with: -``` +```bash rsync -avz --delete --safe-links rsync.apache.org::apache-dist /path/to/mirror ``` @@ -66,7 +66,7 @@ To exclude resource-intensive projects, replace `::apache-dist` with `::apache-d If there is a problem with file/directory permissions, make sure you use a proper umask in your cronjob: -``` +```bash umask 022 ; rsync ... ``` @@ -74,7 +74,7 @@ umask 022 ; rsync ... Private mirrors of ASF downloads cannot host the following file types: -``` +```text exclude => ['/tmp/', '*.md5', '*.MD5', '*.sha1', '*.sha', '*.sha256', '*.sha512', '*.asc', 'MD5SUM', 'SHA*SUM*', '*.mds', '*.sha2', '*.sha3', 'META', @@ -98,7 +98,7 @@ The contents of README.html appear near the bottom of your mirror's home page. Please limit the contents of the README.html to something like: -``` +```text This mirror is donated by www.domain.com [url] to support the Apache open source community. ``` diff --git a/content/pages/key-transition.md b/content/pages/key-transition.md index 2aa38c298..3e335b6d1 100644 --- a/content/pages/key-transition.md +++ b/content/pages/key-transition.md @@ -40,7 +40,7 @@ To generate a strong [RSA key](release-signing.html#rsa) follow [these instructi Both new and old keys should now be contained in the same keyring. Verify this by: -``` +```shell $ gpg --list-secret-keys alice/secring.gpg @@ -64,7 +64,7 @@ You need to perform a number of operations on the new key. Though you can perfor Start by opening an edit session on the new key, for example E2B054B8 -``` +```shell $ gpg --edit-key E2B054B8 gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -88,7 +88,7 @@ Command> The new key needs to be marked as ultimately trusted in this keyring. This will ensure that the web of trust links signed by this key will be trusted automatically. -``` +```text Command> trust pub 4096R/E2B054B8 created: 2009-08-20 expires: never usage: SC @@ -127,7 +127,7 @@ unless you restart the program. Use the old key (AD741727, say) to sign the new key: -``` +```text Command> sign AD741727 pub 4096R/E2B054B8 created: 2009-08-20 expires: never usage: SC @@ -163,7 +163,7 @@ It is convenient to add secondary user ids for current email accounts at this po Then save your changes, which will exit you from edit mode: -``` +```text Command> save ``` @@ -177,7 +177,7 @@ Next, change the default key on the keyring to the new. This ensures that all fu To make the new key the default, set the `default-key` in the `gpg.conf` configuration file. For example, to set the default to `E2B054B8` add: -``` +```text default-key E2B054B8 This setting can be tested by creating a test signature: $ gpg --detach-sig --armor document @@ -193,7 +193,7 @@ Verify that the new key has been chosen by default. Finish the process by uploading the new and old keys to the keyserver: -``` +```shell $ gpg --send-keys E2B054B8 AD741727 ``` @@ -224,7 +224,7 @@ During the transition period, use a single export containing both new and old pu To create a suitable export, supply both key IDs on the command line. For example, to export keys AD741727 (old) and E2B054B8 (new) to FILENAME use: -``` +```shell $ gpg --export --armor --output FILENAME AD741727 E2B054B8 ``` @@ -234,7 +234,7 @@ This exports only the public keys, and so isn't confidential. Replace the old pu During the transitions, use both fingerprints. For example, to fingerprint old key `AD741727` and new key `E2B054B8`, use: -``` +```shell $ gpg --fingerprint AD741727 E2B054B8 pub 1024D/AD741727 2009-08-20 Key fingerprint = CD0C 5281 D0A9 E963 19AF F365 AD81 612A AD74 1727 diff --git a/content/pages/licensing-howto.md b/content/pages/licensing-howto.md index efee31ac0..6d0624f36 100644 --- a/content/pages/licensing-howto.md +++ b/content/pages/licensing-howto.md @@ -52,7 +52,7 @@ Bundling a dependency which is issued under one of the following licenses is str In `LICENSE`, add a pointer to the dependency's license within the distribution and a short note summarizing its licensing: -``` +```text This product bundles SuperWidget 1.2.3, which is available under a "3-clause BSD" license. For details, see deps/superwidget/. ``` @@ -107,7 +107,7 @@ In any case, the principle remains the same: `LICENSE` and `NOTICE` must **exact The following is the text of the `NOTICE` file for Apache Royale: -``` +```text Apache Royale Copyright 2020 The Apache Software Foundation diff --git a/content/pages/mailing-list-moderation.md b/content/pages/mailing-list-moderation.md index d7bf45a97..a87837f96 100644 --- a/content/pages/mailing-list-moderation.md +++ b/content/pages/mailing-list-moderation.md @@ -56,13 +56,13 @@ Moderators can send an email to `listname-list@tlp.apache.org`. Anyone with access to the apmail account can run the following command to get a count of the subscribers: -``` +```bash ezmlm-list~/lists/project/listname| wc -l ``` Remember that there often are people subscribed to the digest version of the list. To find them: -``` +```text ~lists/project/listname/digest ``` @@ -87,7 +87,7 @@ Review the mail to see if it is spam (or other severely misguided mail). If it i To bounce non-spam with a notice to the sender, reply to the `-reject` address in the mail header. If you wish to include a comment with the rejection, the body of the message should look like this: -``` +```text %%% Start comment Your message goes here... %%% End comment @@ -113,13 +113,13 @@ To avoid revealing your personal IP address, you may wish to use an anonymizing If the spam emails are all sent from the same address, try adding them to the 'deny' list: -``` +```text {listname}-deny-subscribe-badposter=menace.com@tlp.apache.org ``` You can find the sender's address in the moderation request in the `cc:` area: -``` +```text Cc: {listname}-allow-tc..-badposter=menace.com@tlp.apache.org ``` @@ -127,7 +127,7 @@ The sender's e-mail address is contained between the '-' (hyphens) immediately f This is already in the correct form for use in the 'deny' subscription request, as the '@' has been changed to '='. In the example above this is: -``` +```text badposter=menace.com ``` @@ -141,7 +141,7 @@ A moderator can fix this by using 'Reply All' to a moderation message from the p It's also possible to set this up in advance, by subscribing the poster to the 'allow' list. For example, if you want `mailbot@host.com` to be able to post, use: -``` +```text {listname}-allow-subscribe-mailbot=host.com@tlp.apache.org ``` @@ -151,7 +151,7 @@ Replace the '@' in the sender email with '='. If you have a troublesome poster, you can un-subscribe them from the list using -``` +```text {listname}-unsubscribe-badboy=menace.com@tlp.apache.org ``` @@ -159,7 +159,7 @@ Send a courtesy email to them to let them know they have been unsubscribed, and Occasionally you will get someone with a poorly-configured spam filter sending automated replies to the list. You can deny their postings using -``` +```text {listname}-deny-subscribe-badposter=menace.com@tlp.apache.org ``` @@ -167,7 +167,7 @@ Send a courtesy email suggesting how they can resolve the problem. If an unsubscribed user was added to the moderation list and is sending spam to the list, remove them by sending an email to: -``` +```text {listname}-allow-unsubscribe-badposter=menace.com@tlp.apache.org ``` @@ -177,7 +177,7 @@ There is an opt-in configuration for problem posters, which lets you su To use it (once it has been enabled) do this: -``` +```text {listname}-sendsubscribertomod-subscribe-badposter=menace.com@tlp.apache.org ``` @@ -199,7 +199,7 @@ Also check whether the emails could have been treated as SPAM by their e-mail cl If a subscriber reports getting a bounce message from ezmlm, ask them to provide the details. For example: -``` +```text Hi! This is the ezmlm program. I'm managing the user@tlp.apache.org mailing list. diff --git a/content/pages/open-access-svn.md b/content/pages/open-access-svn.md index 5985297e5..9123cf83c 100644 --- a/content/pages/open-access-svn.md +++ b/content/pages/open-access-svn.md @@ -58,7 +58,7 @@ The proposal from bimargulies here rests on two foundations: In any case, the argument about the ACL versus culture cuts both ways. Right now, with no change to the LDAP-based ACL, any project could adopt the following policy: -``` +```text Commit Access is granted upon request and acceptance of an ICLA. If you request and receive commit access, you are expected to read, understand, and comply with the project's policies. If you abuse this, we will remove your access. diff --git a/content/pages/openpgp.md b/content/pages/openpgp.md index 2d8adb521..c29c814af 100644 --- a/content/pages/openpgp.md +++ b/content/pages/openpgp.md @@ -38,13 +38,13 @@ GnuPG stores important files, including keyrings and configuration files, in a h For example: -``` +```shell $ gpg --homedir /home/alice/keys --list-keys ``` Projects generally rely on the default. For `\*nux` (linux, BSD, MacOSX, Solaris, AIX) this is: -``` +```text $HOME/.gnupg ``` @@ -55,13 +55,13 @@ command line session. This is useful when [practicing](release-signing.html#safe For example, to set home directory to `alice` when using Linux: -``` +```shell $ export GNUPGHOME=alice ``` When switching key rings, check that the required keyring has been selected by examining the secret keys. For example: -``` +```shell $ gpg --list-secret-keys alice/secring.gpg ----------------- @@ -90,7 +90,7 @@ To configure `gpg` to avoid SHA-1, edit the options in [`gpg.conf`](#configurati To use `SHA512` (recommended): -``` +```text personal-digest-preferences SHA512 cert-digest-algo SHA512 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed @@ -98,7 +98,7 @@ To use `SHA512` (recommended): To use SHA256: -``` +```text personal-digest-preferences SHA256 cert-digest-algo SHA256 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed @@ -111,7 +111,7 @@ configuration has been updated to avoid SHA-1, all new keys generated will use t All existing private keys in the ring need to be updated to indicate that stronger hashes are preferred. For each public-private key pair (generated with the previous defaults): -``` +```shell $ gpg --edit-key F8B7B4FD gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc. This program comes with ABSOLUTELY NO WARRANTY. @@ -154,7 +154,7 @@ All existing private keys in the ring need to be updated to indicate that strong Then upload the modified public key to a public keyserver. For example: -``` +```shell $ gpg --send-keys F8B7B4FD ``` @@ -180,7 +180,7 @@ If the right version of GnuPG is not currently distributed for your platform, yo Checking that the installation has worked and that the version is correct, using either -``` +```shell $ gpg --version gpg (GnuPG) 1.4.10 Copyright (C) 2008 Free Software Foundation, Inc. @@ -200,7 +200,7 @@ Checking that the installation has worked and that the version is correct, using or -``` +```shell $ gpg2 --version gpg (GnuPG) 2.0.12 libgcrypt 1.4.4 @@ -231,7 +231,7 @@ Follow the recommendations about [user ID](release-signing.html#user-id) and [co Follow either -``` +```shell $ gpg --gen-key gpg (GnuPG) 1.4.10; Copyright (C) 2008 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -273,7 +273,7 @@ Follow either or -``` +```shell $ gpg2 --full-gen-key gpg (GnuPG) 2.0.12; Copyright (C) 2009 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -314,7 +314,7 @@ or Check that the configuration has correctly set the key preferences to avoid SHA-1, using either: -``` +```shell $ gpg --edit-key 773447FD gpg (GnuPG) 1.4.10; Copyright (C) 2008 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -338,7 +338,7 @@ Check that the configuration has correctly set the key preferences to avoid SHA- or -``` +```shell $ gpg2 --edit-key A6EE6908 gpg (GnuPG) 2.0.12; Copyright (C) 2009 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -416,19 +416,19 @@ The best way to find a key ID is to obtain it directly from a trusted source, fo If you have a [fingerprint](release-signing.html#fingerprint), the key ID should be the last 8 digits. For example, the ID of the key with this fingerprint: -``` +```text FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8 ``` should be: -``` +```text E2B054B8 ``` You can confirm this using: -``` +```shell $ gpg --list-keys --fingerprint E2B054B8 pub 4096R/E2B054B8 2009-08-20 Key fingerprint = FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8 @@ -444,7 +444,7 @@ When you have the secret key, listing the secret key details allows the key ID t For example, Alice is [transitioning](key-transition.html) and so expects two secret keys in her main keyring. (The case of a single key is similar but less complex.) She lists all secret keys on the keyring: -``` +```shell $ gpg --list-secret-keys alice/secring.gpg ----------------- @@ -461,13 +461,13 @@ Alice verifies that details for only two keys are listed and that there are no u The `sec` lines are: -``` +```text sec 1024D/AD741727 2009-08-20 ``` and -``` +```text sec 4096R/E2B054B8 2009-08-20 ``` @@ -521,13 +521,13 @@ GnuPG seeks to limit accidental private key exports by using different operation By default, operations print their results to the command line. For example, to export all public keys (with ASCII encoding) to the command line, do: -``` +```shell $ gpg --export --armor ``` The `--output` option followed by the name of a file creates that file and stores the output in it. To export all public keys (with ASCII encoding) into a newly created file named `export.asc`, use: -``` +```shell $ gpg --export --output export.asc --armor ``` @@ -539,7 +539,7 @@ The *--armor* option encodes the output using [ASCII characters only](release-si For example, to export all public keys (to the command line) encoded in ASCII, use: -``` +```shell $ gpg --export --armor ``` @@ -552,7 +552,7 @@ The `--export` operation exports public keys. When you don't specify a key, the system exports all public keys in the keyring. For example, to export all public keys to the [command line](#export-option-output) with [ASCII encoding](#export-option-armor): -``` +```shell $ gpg --export --armor ``` @@ -560,7 +560,7 @@ To export specific keys, add identifiers for these keys to the end of the comman For example, to export to the [command line](#export-option-output) with [ASCII encoding](#export-option-armor) the public key with ID `AD741727`, use: -``` +```shell $ gpg --export --armor AD741727 ``` @@ -592,14 +592,14 @@ To ensure that you do not accidentally expose private keys, the GnuPG `--export` Start by [switching](#switch-home) GnuPG [home](#home) to the source. To export all secret keys to a temporary file such as `/tmp/new.sec`, do this: -``` +```shell $ gpg --export-secret-keys --armor --output /tmp/new.sec ``` Import this temporary file into the target keyring. Ensure that GnuPG [home](#home) is set to the target keyring (by either [switching](#switch-home) the current session or opening a new terminal configured to use the target keyring). Then do this: -``` +```shell $ gpg --import /tmp/new.sec gpg: key E2B054B8: secret key imported gpg: key E2B054B8: public key "Alice Example (EXAMPLE NEW KEY) @@ -612,7 +612,7 @@ Import this temporary file into the target keyring. Ensure that GnuPG [home](#ho Check for *secret keys imported* in the output. Listing secret keys for the target keyring should now show the existence of the secret key: -``` +```shell $ gpg --list-secret-keys alice/secring.gpg ----------------- @@ -627,7 +627,7 @@ Check for *secret keys imported* in the output. Listing secret keys for the targ Finally make sure that the temporary file you used cannot be read. We recommend secure deletion. If you are working on Linux, for example, you can use the shred command: -``` +```shell $ shred /tmp/new.sec $ rm /tmp/new.sec ``` @@ -680,7 +680,7 @@ When a key has been compromised, lost or superseded, when possible generate a ne situation. For example, generate an [ASCII armored](release-signing.html#ascii) (for ease of handling) revocation certificate for key `AD741727` like this: -``` +```shell $ gpg --output revoke-AD741727.asc --armor --gen-revoke AD741727 sec 1024D/AD741727 2009-08-20 Alice Example (EXAMPLE OF OLD KEY) @@ -720,7 +720,7 @@ cannot include the specifics and so should indicate this. The process for generating a generic certificate is identical, but you should add a different comment. For example, generate an [ASCII armored](release-signing.html#ascii) (for ease of handling) revocation certificate for key `AD741727` like this: -``` +```shell $ gpg --output revoke-AD741727.asc --armor --gen-revoke AD741727 sec 1024D/AD741727 2009-08-20 Alice Example (EXAMPLE OF OLD KEY) @@ -759,7 +759,7 @@ The process for generating a generic certificate is identical, but you should ad GnuPG supports symmetric (in addition to public key) cryptography, but the ciphers available sometimes differ. Use `gpg --version` to discover which ciphers are available in the current installation: -``` +```shell $ gpg --version gpg (GnuPG) 1.4.9 Copyright (C) 2008 Free Software Foundation, Inc. @@ -778,14 +778,14 @@ GnuPG supports symmetric (in addition to public key) cryptography, but the ciphe In this case, the available ciphers are: -``` +```text 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH ``` Note that most of the ciphers early on the list are weak. This is typical. We recommend that you specify a strong cipher on the command line. For example, to encrypt a document `INPUT_FILENAME` using `AES256` (a strong cipher) and output it to file `ENCRYPTED_FILE`: -``` +```shell $ gpg --cipher-algo AES256 --output ENCRYPTED_FILE --symmetric INPUT_FILENAME ``` @@ -793,7 +793,7 @@ When prompted for a [passphrase](release-signing.html#passphrase), choose a stro The file format contains metadata, including the cipher used. So to decrypt `ENCRYPTED_FILE` into `OUTPUT_FILE` use: -``` +```shell $ gpg --output OUTPUT_FILE --decrypt ENCRYPTED_FILE ``` @@ -830,7 +830,7 @@ Ensure that each `pubkeyAddress` points to the new export [uploaded into your Ap When [transitioning](release-signing.html#transition), include one entry for the old and one for the new key. Yu can use the same URL for both since the target should be the [dual export](key-transition.html#transition-export) you [uploadedearlier](#publish-in-web-space). For example, for keys A6EE6908 (new) and B1313DE2 (old): -``` +```xml A6EE6908 @@ -891,7 +891,7 @@ The basic idea is easy. If Alice has verified Bob's identity and trusts Bob to v Alice starts by verifying the signature: -``` +```shell $ gpg --verify document.asc gpg: Signature made Wed Sep 9 14:33:12 2009 BST using RSA key ID 8F8A2525 gpg: Can't check signature: public key not found @@ -899,7 +899,7 @@ Alice starts by verifying the signature: This indicates that the key used to create this signature is missing from Alice's keyring. This is not unexpected. Alice adds the public key, perhaps by using a public key server or by importing an export, and tries again: -``` +```shell $ gpg --verify document.asc gpg: Signature made Wed Sep 9 14:33:12 2009 BST using RSA key ID 8F8A2525 gpg: checking the trustdb @@ -918,7 +918,7 @@ This output indicates that this key says that Charlie created it. This is a reas Alice examines the signatures on this key: -``` +```shell $ gpg --list-sigs 8F8A2525 pub 2048R/8F8A2525 2009-09-09 uid Charlie (EXAMPLE ONLY NOT FOR DISTRIBUTION) @@ -927,7 +927,7 @@ Alice examines the signatures on this key: This key is signed only by itself. This is not indicative. Unless all keys in the ring have been refreshed, it is possible that a signature has been made but is missing from the ring. Alice refreshes the keys on the ring then verifies once more: -``` +```shell $ gpg --list-sigs 8F8A2525 pub 2048R/8F8A2525 2009-09-09 uid Charlie (EXAMPLE ONLY NOT FOR DISTRIBUTION) @@ -937,7 +937,7 @@ This key is signed only by itself. This is not indicative. Unless all keys in th The key now has a signature from Bob's key - or so says the key. But Alice has met Bob. So, she lists the signatures for that key that may - or may not - be owned by Bob: -``` +```shell $ gpg --list-sigs 1B912854 pub 2048R/1B912854 2009-09-09 uid Bob___ (EXAMPLE ONLY NOT FOR DISTRIBUTION) diff --git a/content/pages/patch.md b/content/pages/patch.md index 752bbd5a3..eca0aebb2 100644 --- a/content/pages/patch.md +++ b/content/pages/patch.md @@ -17,7 +17,7 @@ If all this works, you can create your patch. Remove all build products and remn Apache projects prefer the unified diff format. The subversion tool creates that automatically. If you use other tools, please refer to their documentation for details on setting the diff format. -``` +```text # location where the modules are stored cd checkout

# directory of the module
diff --git a/content/pages/pelican-buildbot.md b/content/pages/pelican-buildbot.md
index 90fd10215..ec78d735b 100644
--- a/content/pages/pelican-buildbot.md
+++ b/content/pages/pelican-buildbot.md
@@ -43,7 +43,7 @@ Create the repository for the website content using the > pelicanconf.py
diff --git a/content/pages/project-site.md b/content/pages/project-site.md
index 49a013b45..8bd5cc5ab 100644
--- a/content/pages/project-site.md
+++ b/content/pages/project-site.md
@@ -132,7 +132,7 @@ Using [.asf.yaml](asf-yaml.html) with a Git repository, once you have your gener
 
 To do so, add or edit `.asf.yaml` in the staging branch (where the build output is generated) and add the following (assuming your staging branch is asf-staging):
 
-```
+```yaml
 staging:
   profile: ~
   whoami:  asf-staging
@@ -145,7 +145,7 @@ For more details, see [.asf.yaml](asf-yaml.html).
 
 When you are ready to publish a branch of your Git web site repository to your project web site, you can use `.asf.yaml`:
 
-```
+```yaml
 publish:
   whoami:  asf-site
 ```
diff --git a/content/pages/publishing-maven-artifacts.md b/content/pages/publishing-maven-artifacts.md
index 90e319b8e..a20315130 100644
--- a/content/pages/publishing-maven-artifacts.md
+++ b/content/pages/publishing-maven-artifacts.md
@@ -34,7 +34,7 @@ To use the ASF Nexus repository, follow these steps.
 
 Inherit the Apache Parent POM like this:
 
-```
+```xml
 
   org.apache
   apache
@@ -56,7 +56,7 @@ You must sign all artifacts with a key that is publicly verifiable. Follow the i
 
 The gpg plugin can prompt for the key (input is masked) or you can configure it to use an agent.
 
-```
+```xml
 
 ...
   
@@ -97,7 +97,7 @@ This will build artifacts and sources and sign them.
 
 ### 2. Publish a snapshot ###
 
-```
+```text
 mvn deploy
 ...
 [INFO] [deploy:deploy]
@@ -113,7 +113,7 @@ mvn deploy
   
 ### 3. Prepare the release ###
 
-```
+```bash
 mvn release:clean
 mvn release:prepare
 ```
@@ -137,7 +137,7 @@ Now you must close the staging repository to indicate to Nexus that the build is
 
 1. If you get an **error message** like this:
 
-```
+```text
 [INFO] Unable to tag SCM
 Provider message:
 The svn tag command failed.
@@ -152,7 +152,7 @@ Then use a Subversion client 1.6 or newer and run `svn update`.
 
 2. If you get an **error message** similar to:
 
-```
+```text
 [ERROR] BUILD FAILURE
 [INFO]
 [INFO] Unable to tag SCM
diff --git a/content/pages/release-download-pages.md b/content/pages/release-download-pages.md
index d24fac97d..8d78bf73f 100644
--- a/content/pages/release-download-pages.md
+++ b/content/pages/release-download-pages.md
@@ -104,7 +104,7 @@ Provide links to the checksum and signature for the artifact next to the downloa
 
 For example, for artifact foo-1.0.0.tar.gz contained in bar/foo :
 
-```
+```text
 `zip`
 `PGP`
 ```
@@ -123,7 +123,7 @@ Provide clear and easy links to the KEYS, sums and signatures from the download
 
 Include a reminder text with links to more information for users. For example:
 
-```
+```text
 Note: when downloading, please check the
 sha checksum
 and verify the 
diff --git a/content/pages/release-signing.md b/content/pages/release-signing.md
index 993607759..639b6dd41 100644
--- a/content/pages/release-signing.md
+++ b/content/pages/release-signing.md
@@ -102,7 +102,7 @@ It is
 To create one using GNU Privacy Guard for file
 `foo.tar.gz`, type:
 
-```
+```shell
 $ gpg --armor --output foo.tar.gz.asc --detach-sig foo.tar.gz 
 ```
 
@@ -111,19 +111,19 @@ $ gpg --armor --output foo.tar.gz.asc --detach-sig foo.tar.gz
 MD5 is a well known  message
 digest algorithm. Many tools are available to calculate these sums. For example, you can use OpenSSL:
 
-```
+```shell
 $ openssl md5 < file
 ```
 
 Platform-specific applications are also common, such as `md5sum` on linux:
 
-```
+```shell
 $ md5sum file
 ```
 
 With GnuPG:
 
-```
+```shell
 $ gpg --print-md MD5 [fileName] > [fileName].md5
 
 ```
@@ -136,7 +136,7 @@ Run the command in the same directory as the file so the output only contains th
 
 Like MD5, SHA is a message digest algorithm. Using GnuPG, you can create a SHA1 signature as follows:
 
-```
+```shell
   $ gpg --print-md SHA1 [fileName] > [fileName].sha1
 ```
 
@@ -145,7 +145,7 @@ lengths (256 and 512 bits respectively). These longer variations are less vulner
 
 To create a `SHA512` checksum use:
 
-```
+```shell
   $ sha512sum [fileName] > [fileName].sha512
 ```
 
@@ -186,7 +186,7 @@ Do **not** store your private key on any ASF machine. Do **not** create signatur
 
 When you use GNU Privacy Guard you may see a warning similar to:
 
-```
+```text
 gpg: WARNING: using insecure memory!
 gpg: please see http://www.gnupg.org/faq.html for more information
 ```
@@ -260,7 +260,7 @@ There are two common ways to upload a key to a public key s
   
 For example, using GNU Privacy Guard, send the key with ID B1313DE2 to the default public key server by:
 
-```
+```shell
 $ gpg --send-key B13131DE2
 ```
 
@@ -271,7 +271,7 @@ You must export each changed key separately.
 The public web of trust grows constantly as people sign new keys and upload the new signatures onto the network of public key servers. You should refresh public keys periodically to make sure that your local web of trust is as full as possible. Many OpenPGP clients make it easy to refresh keys by
 querying a public key server. For example, to refresh all keys using GNU Privacy Guard, use:
 
-```
+```shell
 $ gpg --refresh-keys
 ```
 
@@ -282,7 +282,7 @@ You can export a public key through ASCII armored revocation certificate for key `bob` and save it to `revoke.asc` using revocation certificate using GNU Privacy Guard, import the certificate:
 
-```
+```shell
 $ gpg --import revoke.asc 
 gpg: key 4A03679A: "Some User" revocation
 certificate imported
@@ -561,7 +561,7 @@ When you _revoke_ a key, it is marked in the key ring. Whenever a message signed
 
 For example, when you verify a revoked key, GNU Privacy Guard issues the following comment:
 
-```
+```shell
 $ gpg --verify message.asc.message 
 gpg: Signature made Sat Apr  8 09:28:31 2006 BST using DSA key ID 4A03679A
 gpg: Good signature from "Some User "
@@ -585,14 +585,14 @@ You can use public key cryptography to test whether a particu
 
 For example, when using GNU Privacy Guard you verify the signature `foo-1.0.tar.gz.asc` for release `foo-1.0.tar.gz` using the following command:
 
-```
+```shell
 $ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
 ```
 
 A signature is valid, if `gpg` verifies the `.asc` as a _good signature_, and doesn't complain about expired
 or revoked keys. Technically :
 
-```
+```shell
 $ gpg --verify --status-fd 1 foo-1.0.tar.gz.asc foo-1.0.tar.gz
 ```
 
@@ -609,7 +609,7 @@ You can also check the integrity of a release by 
 
What does 'Public key not found' mean when I try to verify a signature?

 To verify a signature, you need the release's public key. For example, when using GNU Privacy Guard, if you have never imported the appropriate public key, you will see a message like this:
 
-```
+```shell
 $ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
 gpg: Signature made Mon Sep 26 22:26:18 2005 BST using RSA key ID 00000000
 gpg: Can't check signature: public key not found
@@ -619,7 +619,7 @@ You can often download unknown keys from a public key serve
 
 Apache projects normally keep the developers' public keys in a file called `KEYS`. You may be able to find that file on the project's website, or in their code repository. Use
 
-```
+```shell
   $ gpg --import KEYS
 ```
 
@@ -654,7 +654,7 @@ Do not trust a file with an invalid signature. You can trust a file with a valid
 
 For example, when you use GNU Privacy Guard, a message similar to the following indicates that the signature is invalid:
 
-```
+```shell
 $ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
 gpg: Signature made Mon Sep 26 22:26:18 2005 BST using RSA key ID 00000000
 gpg: BAD signature from "someone@example.org"
@@ -662,7 +662,7 @@ gpg: BAD signature from "someone@example.org"
 
 A message similar to the following indicates that the signature is valid but for an untrusted key:
 
-```
+```shell
 $ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
 gpg: Signature made Mon Sep 26 22:05:28 2005 BST using RSA key ID 00000000
 gpg: Good signature from "someone@example.org"
@@ -688,7 +688,7 @@ On occasion, the user (who understands the risks) may trust a key but not consid
 
 For example, with GNU Privacy Guard use:
 
-```
+```shell
 $ gpg --lsign-key someuser
 ```
 
diff --git a/content/pages/request-bug-tracker.md b/content/pages/request-bug-tracker.md
index a28e82537..53cddef16 100644
--- a/content/pages/request-bug-tracker.md
+++ b/content/pages/request-bug-tracker.md
@@ -23,7 +23,7 @@ Infra will respond within a couple of days, either with a request for clarificat
 
 Enabling GitHub Issue tracking for your project is self-serve. In the .asf.yaml file for your repository, locate the `github` section and set the `issues` option to true, as in the example below.
 
-```
+```yaml
 github:
   features:
     # Enable wiki for documentation
diff --git a/content/pages/svn-basics.md b/content/pages/svn-basics.md
index d11b7a22f..f786cc316 100644
--- a/content/pages/svn-basics.md
+++ b/content/pages/svn-basics.md
@@ -40,7 +40,7 @@ This will prompt you to enter a svn password of your choice. If you cannot log i
 
 When you make changes to the repository, you can commit them with your username/password combination, i.e.
 
-```
+```shell
 $ svn co https://svn.apache.org/repos/asf/excalibur/trunk/ excalibur-trunk
 $ cd excalibur-trunk
 $ echo "test" > test.txt
@@ -55,7 +55,7 @@ $ svn commit --username your-name --password your-password \
 
 Committers need to configure their svn client properly. One particular issue is OS-specific line endings for text files. When you add a new text file, especially when applying patches from Bugzilla, first ensure that the line-endings are appropriate for your system, then do:
 
-```
+```bash
 svn add test.txt svn propset svn:eol-style native test.txt
 ```
 
@@ -73,7 +73,7 @@ Pay attention to the messages from your svn client when you do `svn commit`.
 
 The server certificate for `https://svn.apache.org/` is a real SSL certificate. However, Subversion, by default, does not currently ship with a list of trusted CAs. So, here's some information to help you verify the validity of our certificate:
 
-```
+```text
  - Hostname: *.apache.org
  - Valid: from Jul  1 00:00:00 2019 GMT until Jun 30 23:59:59 2021 GMT
  - Issuer: Sectigo RSA Domain Validation Secure Server CA, Sectigo Limited, Salford, Greater Manchester, GB
@@ -104,7 +104,7 @@ If you really do want the entire ASF repository, *don't* use `svnsync`. Instead,
 
 Run `svn info` and check that the URL starts with `https://`. If it starts with `http://`, run:
 
-```
+```shell
 $ svn switch --relocate http://svn.apache.org https://svn.apache.org
 ```
 
diff --git a/content/pages/user-ssh.md b/content/pages/user-ssh.md
index 694d7452e..139c1eef6 100644
--- a/content/pages/user-ssh.md
+++ b/content/pages/user-ssh.md
@@ -22,7 +22,7 @@ Remember to keep your client up to date with security patches. Pay close attenti
 
 The OpenSSH client uses by default configuration files in the `~/.ssh` directory. The main configuration file is `~/.ssh/config` and is optional. It may exist already. If it does not, you can create it in a simple text format. Group together instructions for a particular host (or group of hosts). Here is a suggested basic configuration:
 
-```
+```text
 
 # Apply to all hosts
 
@@ -41,7 +41,7 @@ Many other options are available.
 
 To diagnose what's going wrong with an OpenSSH connection, run the client in verbose mode. To do this just add `-v`:
 
-```
+```bash
 ssh -v -l yourApacheID some-project-server.apache.org
 ```
 
@@ -100,7 +100,7 @@ SSH employs the known hosts mechanism to prevent Repository types
-    -  Public and private repositories
-  - Repository checkout
-  - Using .asf.yaml
-  - Committers: getting started
-  - Windows users
-  - Line endings
-  - Troubleshooting
-  - Further reading
+- Repository types
+  - Public and private repositories
+- Repository checkout
+- Using .asf.yaml
+- Committers: getting started
+- Windows users
+- Line endings
+- Troubleshooting
+- Further reading
 
 
Repository types

 
@@ -55,7 +55,6 @@ https://gitbox.apache.org/repos/asf/reponame.git
 - **Committers**: `$ git clone https://gitbox.apache.org/repos/asf/reponame.git`
 - **Non-Committers**: `$ git clone http://gitbox.apache.org/repos/asf/reponame.git`
 
-
 
Using .asf.yaml

 
 `.asf.yaml` is a branch-specific YAML configuration file that a project may create (using a text editor of your choice) and put in the root of a Git repository to control features such as
diff --git a/content/pages/infra-contact.md b/content/pages/infra-contact.md
index 7349d1d10..7ab909311 100644
--- a/content/pages/infra-contact.md
+++ b/content/pages/infra-contact.md
@@ -42,7 +42,7 @@ That depends on your role and what you want to do. If this chart doesn't help, I
   
     discuss something publicly with Infra, or ask Infra a question
     The #asfinfra Slack channel, or by taking part in a Roundtable (the end of each Roundtable session is an open-mic opportunity for your comments or questions). See https://infra.apache.org/roundtable.html.
-    Consider these semi-public forums which are not suitable for confidential information.    
+    Consider these semi-public forums which are not suitable for confidential information.  
   
   
     get your IP unblocked