This is an automated email from the ASF dual-hosted git repository. chibenwa pushed a commit to branch staging in repository https://gitbox.apache.org/repos/asf/james-site.git
commit 9becc5fd9c0b669200802b98db48eb14fa7c7d6c Author: Benoit TELLIER <[email protected]> AuthorDate: Sun Aug 23 23:09:17 2026 +0700 [DOC] Relocate community section to james-site root --- doc-sites/ui-overrides/partials/header-content.hbs | 2 +- docs/antora.yml | 2 + docs/modules/ROOT/images/linagora.png | Bin 0 -> 14370 bytes docs/modules/ROOT/nav.adoc | 18 ++ .../{index.adoc => building-the-website.adoc} | 2 +- docs/modules/ROOT/pages/contributing.adoc | 205 ++++++++++++++++++ docs/modules/ROOT/pages/download.adoc | 4 + docs/modules/ROOT/pages/guidelines.adoc | 146 +++++++++++++ docs/modules/ROOT/pages/index.adoc | 90 +++----- docs/modules/ROOT/pages/mailing-lists.adoc | 162 +++++++++++++++ docs/modules/ROOT/pages/release.adoc | 230 +++++++++++++++++++++ docs/modules/ROOT/pages/support.adoc | 28 +++ docs/modules/ROOT/pages/website.adoc | 182 ++++++++++++++++ docs/modules/ROOT/partials/antora.adoc | 60 ++++++ 14 files changed, 1072 insertions(+), 59 deletions(-) diff --git a/doc-sites/ui-overrides/partials/header-content.hbs b/doc-sites/ui-overrides/partials/header-content.hbs index caa1c0baa..e6553b0e5 100644 --- a/doc-sites/ui-overrides/partials/header-content.hbs +++ b/doc-sites/ui-overrides/partials/header-content.hbs @@ -29,7 +29,7 @@ <a class="navbar-link" href="#">Community</a> <div class="navbar-dropdown"> <!-- Not ideal but dropping the version in the href requires tweaking james-projet docs module first --> - <a class="navbar-item" href="/james-project/3.6.0/community/mailing-lists.html">Mailing lists</a> + <a class="navbar-item" href="/james-site/latest/mailing-lists.html">Mailing lists</a> <a class="navbar-item" href="https://gitter.im/apache/james-project";><svg version="1.1" xmlns="http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink"; viewBox="0 0 32 32" class="logo-gitter-sign" data-v-44ebcb1a=""><rect x="15" y="5" width="2" height="10"></rect> <rect x="10" y="5" width="2" height="20"></rect> <rect x="5" y="5" width="2" height="20"></rect> <rect width="2" height="15"></rect></svg> Gitter</a> <a class="navbar-item" href="https://twitter.com/ApacheJames";> <span class="icon"> diff --git a/docs/antora.yml b/docs/antora.yml index 2e5257eae..8698c95b4 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -2,3 +2,5 @@ name: james-site title: Apache James Site version: 'latest' prerelease: true +nav: +- modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/images/linagora.png b/docs/modules/ROOT/images/linagora.png new file mode 100644 index 000000000..de0a185b2 Binary files /dev/null and b/docs/modules/ROOT/images/linagora.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 000000000..43b661f27 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,18 @@ +* xref:homepage.adoc[] +* xref:index.adoc[] +** xref:mailing-lists.adoc[] +** xref:contributing.adoc[] +** xref:guidelines.adoc[] +** xref:download.adoc[] +** xref:website.adoc[] +** xref:building-the-website.adoc[] +** xref:release.adoc[] +** xref:support.adoc[] +** Apache Software Foundation +*** https://www.apache.org/[ASF] +*** https://www.apache.org/foundation/getinvolved.html[Get involved] +*** https://www.apache.org/foundation/faq.html[FAQ] +*** https://www.apache.org/licenses/[Licenses] +*** https://www.apache.org/security/[Security] +*** https://www.apache.org/foundation/sponsorship.html[Sponsorship] +*** https://www.apache.org/foundation/thanks.html[Thanks] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/building-the-website.adoc similarity index 99% copy from docs/modules/ROOT/pages/index.adoc copy to docs/modules/ROOT/pages/building-the-website.adoc index fe5d25d33..bea02fc8e 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/building-the-website.adoc @@ -1,4 +1,4 @@ -= Apache James website += Building the website This repository is used for storing (some) content for https://james.apache.org[Apache James] website. diff --git a/docs/modules/ROOT/pages/contributing.adoc b/docs/modules/ROOT/pages/contributing.adoc new file mode 100644 index 000000000..ac506ac11 --- /dev/null +++ b/docs/modules/ROOT/pages/contributing.adoc @@ -0,0 +1,205 @@ += Contributing + +This document defines the different ways available for contributing to the Apache James project. + +To keep you informed on James issues, subscribe to the relevant xref:mailing-lists.adoc[mailing lists]. + +== Be involved in the community + +An easy start is to be involved in the community. + +Share your experiences with James, your needs, your enhancements proposition via the +xref:mailing-lists.adoc[mailing lists], on https://gitter.im/apache/james-project[Gitter], or on our +https://issues.apache.org/jira/projects/JAMES/issues[Bug Tracker]. + +Don't hesitate to write articles and blog posts. Use your preferred media to spread the love! + +== Reporting bugs + +Many improvements come as a direct result of bug reports. + +To report a bug, please use the appropriate Bug Tracker JIRA link according to the project you want to address: + +* https://issues.apache.org/jira/browse/JAMES[Server] +* https://issues.apache.org/jira/browse/MAILET[Mailet] +* https://issues.apache.org/jira/browse/MAILBOX[Mailbox] +* https://issues.apache.org/jira/browse/PROTOCOLS[Protocols] +* https://issues.apache.org/jira/browse/MPT[MPT] +* https://issues.apache.org/jira/browse/MIME4J[Mime4j] +* https://issues.apache.org/jira/browse/JSIEVE[jSieve] +* https://issues.apache.org/jira/browse/JSPF[jSPF] +* https://issues.apache.org/jira/browse/JDKIM[jDKIM] + +Once you are logged on the appropriate JIRA page, click on the red Create button, then complete the different fields +as accurately as possible, so that any user can reproduce the reported bug. Also, note that all your information must be +readable (use markdown). + +Then, you have to click on Create to submit your bug. + +=== Reporting security vulnerabilities + +http://www.apache.org/security/[Security vulnerabilities] should be announced to the Apache Security team. +PMCs will be notified about them, and will work hard to propose fixes as fast as possible. + +Specific details about security in James can be found here. + +== Documentation + +Documentation is an easy way to get on board! Check out the +link:https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20documentation%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~documentation] +label on JIRA to get some ideas. +Report on JIRA the typos you spot, the information you miss, and any improvement you can think of. +The next step is to contribute the documentation changes via https://github.com/apache/james-project/tree/master/docs/modules[Git]. + +To edit an existing document try to edit the adoc version in `docs/modules` (check it out from Git) and if you can, submit a +patch as for xref:_code_patches[Code Patches]. + +If you want to contribute new files please try to use the AsciiDoc format as shown in `docs/modules`. + +If all this seems like unnecessary nonsense, send us whatever you like, we'd still be happy to receive good documentation. + +Each of the Apache James projects has its own documentation maintained with the automated build. Once a build is done, +the documentation can be further committed in the https://git-wip-us.apache.org/repos/asf/james-site.git[site module] +which will be automatically published via gitpubsub to http://james.apache.org[Apache James web site]. + +== Idea or design proposals + +People can submit ideas, features or design changes proposals by discussing it through the +xref:mailing-lists.adoc[mailing lists]. + +Structuring design changes are tracked by link:https://github.com/joelparkerhenderson/architecture-decision-record[ADRs] +(Architecture Decision Records). A discussion on the mailing list getting a consensus of the community can be the object +of the writing of an ADR to confirm the change agreed upon. The Project Member Committee will take care of maintaining such +records but anyone should feel free to help on such a task by proposing ADRs related to his work. + +ADRs *MUST* be submitted under the folder `src/adr` via a pull request. The standards used for writing an ADR are +described in the https://github.com/apache/james-project/blob/master/src/adr/0001-record-architecture-decisions.md[first ADR] +written for the Apache James project. + +The number of the ADR should be incremental. If another ADR gets merged concurrently, the committer is responsible for +updating its number accordingly. + +When the ADR reaches a consensus within the community and is accepted, it can be merged and goes into effect. + +An ADR can't be removed after being accepted and merged. However, a new ADR can supersede a previous one. This is so +we are able to keep track on all the decisions being made regarding the project. + +== How to contribute some code? + +We encourage discussions prior code contributions on the xref:mailing-lists.adoc[mailing lists]. For significant design +changes the writing of xref:#_idea_or_design_proposals[ADRs] is encouraged. + +Your code contribution *must* be backed by a xref:_reporting_bugs[JIRA ticket]. + +* Clone the source code of the project from its link:git://git.apache.org/james-project.git[apache git repository] or its +https://github.com/apache/james-project[GitHub] +* Create your branch and name it with the JIRA ticket number. +* Create a Pull Request on GitHub with your branch name and prefix its different commits with the same name. +* A build will be started for your work on the link:https://ci-builds.apache.org/job/james/job/ApacheJames/[Apache CI]. +* Active contributors will review your work, and merge it. + +A valid commit comment might be: + +``` +JAMES-2285 My awesome commit title + +Here is some more details about what my commit does, and the rationals of the choice I took. +``` + +Alternatively you can create a patch as xref:_code_patches[outlined below], and attach it to the JIRA ticket. + +=== Licenses + +All contributions to the James project are made under the https://www.apache.org/licenses[Apache license 2.0] + +=== Contributions proposals + +* We reference some easy tasks to start with: +https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20newbie%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~newbie] +* We have a collection of minor fixes awaiting contributions: +https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20easyfix%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~easyfix] +* Challenge yourself with some cool features we thought to: +https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20feature%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC[~feature] + +Additional ideas are more than welcome. Don't hesitate to discuss that with us! + +=== Coding standards + +While we are glad to accept contributions to documentation from anyone, in almost any format, because its much better +than none, please consider these guidelines to help us to assimilate your contribution. + +Submissions to the James project must follow the coding conventions outlined in the +link:https://github.com/apache/james-project/blob/master/checkstyle.xml[checkstyle document], which runs +upon `mvn compile` and all phases which depend on `compile`. Not respecting it will halt the build, and means +your contribution would not be +acceptable. + + +*Developers who commit code that does not follow the coding conventions outlined in this document will be responsible +for fixing their own code.* `. + +[start=3] +. Four spaces. *No tabs.* Period. +The James mailing list receives commit messages that are almost impossible to read if tabs are used. +. Use Unix linefeeds for all .java source code files. Only platform-specific files (e.g. .bat files for Windows) should +contain non-Unix linefeeds. +. Javadoc *MUST* exist on all API methods. Contributing a missing javadoc for any method, class, variable, etc., will be +GREATLY appreciated as this will help to improve the James project. +. The standard Apache license header *MUST* be placed at the top of every file. +. Your change set *MUST* be covered by tests. We also strongly appreciate integration tests. +. We also require the following best practice regarding maven and the *pom.xml*: + +** Define your dependency versions in james-project pom.xml. This structurally ensures all projects get the same version, +and that there is no version clashes. +** Don't use _org.apache.james_ groupId for internal dependencies. Use _${james.groupId}_. If not, you break the policies +for automatic sorting, as well as make it more ambiguous. One exception is apache-mime4j-* artifacts which share the +james groupId despite living in a different repository. +** You should be ordering your dependencies. The sort order of tags and dependencies in the pom is automatically enforced at build time. By default the build +will fail if violations are detected. + +The pom file ordering can be quickly checked using : +``` +mvn validate +``` +If you get an error and want the tool to fix it for you, you can use : +``` +mvn validate -PsortPom +``` +The `sortPom` profile can be used on all maven phases. Make sure to review the changes made by the tool, it is known to +sometimes remove whitespaces which may not be desirable. + +=== Code patches + +While we definitely prefer receiving contributions under the form of xref:#_how_to_contribute_some_code[GitHub pull requests], +in order to still be vendor neutral on the contribution process, we do accept submission of patches, in a process described +below. + +Patches should be attached to the corresponding JIRA issue. + +Always use diff -u to generate patches, so we can apply them using 'patch'. + +Make sure the patch only contains what is intended, your checkout could be outdated. + +Make sure it conforms to the code standards, otherwise it may be ignored. It is OK to make a single patch covering +several files, but please only one issue at a time. + +Briefly outline the reason for your patch, the solution your patch implements, why a patch is needed and why your code +will solve the problem. Note any bug numbers your patch addresses. + +The reason for these rules is so that committers can easily see what you are trying to achieve, it is their +responsibility to manage the code and review submissions, if you make it easy for them to see what you are doing your +patch is more likely to be committed quickly. + +=== Experimental nix support + +There is work in progress to support a more reproductible dev environment so you don't have to figure out what to install or how. + +This work is based on nix flakes if you are not familiar with nix or flakes you can find more information in the https://nix.dev/manual/nix/2.28/command-ref/new-cli/nix3-flake.html[official documentation], https://wiki.nixos.org/wiki/Flakes[official wiki] or in https://zero-to-nix.com/concepts/flakes/[dedicated] community https://nix.dev/concepts/flakes[resources]. + +If you already have the nix package manager installed you should be able to use the following command to enter the predefined build env (experimental nix flag `flakes` is required, `nix-command` is recommended as it is used in many examples) with : + +``` +nix develop --no-update-lock-file +``` + +If you encounter an issue, leave a comment on the corresponding jira issue https://issues.apache.org/jira/browse/JAMES-4175[JAMES-4175] or create a bug and link it as related to https://issues.apache.org/jira/browse/JAMES-4175[JAMES-4175] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/download.adoc b/docs/modules/ROOT/pages/download.adoc new file mode 100644 index 000000000..d673199d7 --- /dev/null +++ b/docs/modules/ROOT/pages/download.adoc @@ -0,0 +1,4 @@ += Download Apache James releases +:navtitle: Download releases + +https://james.apache.org/download[Download Apache James releases] diff --git a/docs/modules/ROOT/pages/guidelines.adoc b/docs/modules/ROOT/pages/guidelines.adoc new file mode 100644 index 000000000..5e06234e5 --- /dev/null +++ b/docs/modules/ROOT/pages/guidelines.adoc @@ -0,0 +1,146 @@ += Apache James Project guidelines +:navtitle: Guidelines + +This document defines the guidelines for the Apache James Project. It includes definitions of how conflict is being +resolved by voting and who is able to vote. + +The objective here is to avoid unnecessary conflicts over changes and continue to produce a quality system in a timely +manner. Not all conflict can be avoided, but at least we can agree on the procedures for conflicts to be resolved. + +== People, Places, and Things + +=== Apache James Project Management Committee + +The group of volunteers who are responsible for managing the Apache James Project. This includes deciding what is +distributed as products of the Apache James Project, maintaining the Project's shared resources, speaking on behalf of +the Project, resolving license disputes regarding Apache James products, nominating new PMC members or committers, +and establishing these guidelines. + +Membership in the Apache James PMC is by invitation only and must be approved by consensus of the active Apache James +PMC members. A PMC member is considered inactive by their own declaration or by not contributing in any form to the +project for over six months. An inactive member can become active again by reversing whichever condition made them +inactive (i.e., by reversing their earlier declaration or by once again contributing toward the project's work). +Membership can be revoked by a unanimous vote of all the active PMC members other than the member in question. + +=== Apache James Committers + +The group of volunteers who are responsible for the technical aspects of the Apache James Project. This group has write +access to the appropriate source repositories and these volunteers may cast non-binding votes on any technical discussion. + +Membership as a Committer is by invitation only and must be approved by consensus of the active Apache James PMC members. +A Committer is considered inactive by their own declaration or by not contributing in any form to the project for over +six months. An inactive member can become active again by reversing whichever condition made them inactive (i.e., by +reversing their earlier declaration or by once again contributing toward the project's work). Membership can be revoked +by a unanimous vote of all the active PMC members (except the member in question if they are a PMC member). + +=== Mailing list + +The Apache committers' primary mailing list for discussion of issues and changes related to the project +(xref:mailing-lists.adoc#_server_developer_list[[email protected]]). Subscription to the list is open, but +only subscribers can post directly to the list. + +=== Private list + +The Apache James Project's private mailing list for discussion of issues that are inappropriate for public discussion, +such as legal, personal, or security issues prior to a published fix. Subscription to the list is only opened to Apache +James PMC members and Apache Software Foundation Members. + +Topics to be discussed on the private mailing list: + + - Discussion of board reports. PMC members need to report quarterly project activity to the Apache board of directors, +which is done through link:https://reporter.apache.org[reporter.apache.org]. Prior report submission, the draft should +be discussed on the private mailing list. + - Discussions of link:https://community.apache.org/newcommitter.html[new committers, new PMCs], including proposition discussions, votes and process follow up. + - Handling of xref:contributing.adoc#_reporting_security_vulnerabilities[security vulnerability reports], and CVE publication. + +Other topics should be discussed/voted on server-dev instead. + +=== GIT + +All of the Apache James products are maintained in shared information repositories using GIT on git-wip-us.apache.org. +The Apache committers have write access to these repositories; everyone has read access via anonymous GIT. + +== Consensus + +As a community we are seeking link:https://community.apache.org/committers/decisionMaking.html[consensus] in our +decision making. + +We actively rely on link:https://community.apache.org/committers/lazyConsensus.html[lazy consensus] for most of our +decisions, be them validating xref:contributing.adoc#_how_to_contribute_some_code[code changes], enacting +xref:contributing.adoc#_idea_or_design_proposals[design decisions]. + +All code modifications should achieve lazy consensus under the form of GitHub pull requests. + +=== Voting + +Some decisions might require to vote: + + - xref:release.adoc[releases] + - establishing a new sub-project + - retiring sub-projects + - taking a decision when lazy consensus failed. + +Note that we encourage discussing the issues prior to trigger a vote. That way bad surprises may be avoided ahead of time. + +Any of the Apache James Committers may vote on any issue or action item. However, the only binding votes are those cast +by active members of the Apache James PMC; if the vote is about a change to source code or documentation, the primary +author of what is being changed may also cast a binding vote on that issue. All other votes are non-binding. All +contributors are encouraged to participate in decisions, but the decision itself is made by those who have been long-time +contributors to the project. In other words, the Apache Project is a minimum-threshold meritocracy. + +The act of voting carries certain obligations -- voting members are not only stating their opinion, they are agreeing +to help do the work of the Apache Project. Since we are all volunteers, members often become inactive for periods of +time in order to take care of their "real jobs" or devote more time to other projects. It is therefore unlikely that the +entire group membership will vote on every issue. To account for this, all voting decisions are based on a minimum quorum. + +Each vote can be made in one of three flavors: + +*+1* +Yes, agree, or the action should be performed. On some issues, this vote is only binding if the voter has tested the +action on their own system(s). + +*+-0* +Abstain, no opinion, or I am happy to let the other group members decide this issue. An abstention may have detrimental +effects if too many people abstain. + +*-1* +No. On issues where consensus is required, this vote counts as a veto. All vetoes must include an explanation of why the +veto is appropriate. A veto with no explanation is void. No veto can be overruled. If you disagree with the veto, you +should lobby the person who casts the veto. Voters intending to veto an action item should make their opinions known to +the group immediately, so that the problem can be remedied as early as possible. + +An action item requiring consensus approval must receive at least 3 binding +1 votes and no vetoes. An action item +requiring majority approval must receive at least 3 binding +1 votes and more +1 votes than -1 votes (i.e., a majority +with a minimum quorum of three positive votes). All other action items are considered to have lazy approval until +someone votes -1, after which point they are decided by either consensus or a majority vote, depending upon the type +of action item. + +All votes must be either sent to the mailing list for that action item. + +Votes are to remain open for 72 hours after which the developer who put forth the vote should tabulate the result and +send this to the mailing list. A developer should be sensitive to holidays that could dampen participation in the vote. + +== Section for new committers + +First congratulation for your involvement! + +As part of the link:https://community.apache.org/newcommitter.html[process to become a committer], the following steps should have had been emailed to you: + + - Signing of link:https://www.apache.org/licenses/#clas[Contributor License Agreement] + - Establishing an Apache profile with the Apache secretary. + - Access will directly be granted on the link:https://issues.apache.org/jira/projects/JAMES[JIRA], +the ASF Git repository and the link:https://ci-builds.apache.org/job/james/job/ApacheJames/[ci]. + - Extra steps should be taken for xref:#_accessing_apache_github_as_a_committer[GitHub access]. + - A PMC should have had announced your nomination. If you have not already been doing it, we strongly +encourage you to write an email on public mailing list, presenting you, and your motivations toward +contributing on Apache James. A reply to the announcement would do the trick! + +=== Accessing Apache GitHub as a Committer + +- Verify you have a GitHub ID enabled with link:https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/[2FA] +- Enter your GitHub ID into your link:https://id.apache.org/[Apache ID profile] +- Merge your Apache and GitHub accounts using link:https://gitbox.apache.org/setup/[GitBox] (Apache Account Linking utility). You should see 3 green checks in GitBox. + +Wait at least 30 minutes for an email inviting you to Apache GitHub Organization and accept invitation. + +- After accepting the GitHub Invitation verify that you are a member of the link:https://github.com/orgs/apache/teams/james-committers[GitHub Apache James team]. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index fe5d25d33..7b7bcee87 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,71 +1,47 @@ -= Apache James website += Apache James Community +:navtitle: Community -This repository is used for storing (some) content for https://james.apache.org[Apache James] website. +Apache James Project is an Open Source all-volunteer project obtaining its strength from its Community made of +developers and users. All are welcome to the Community! -It's also used to build and publish the website. +== Join the community +There are many ways for Users, Developers, Curious and Fans to join and be part of the James Community: -== How to build the website + * https://james.apache.org/[Apache James Website] + * xref:mailing-lists.adoc[Mailing lists]: Subscribe to the appropriate Mailing Lists according to your interests and profile. + * https://gitter.im/apache/james-project[Gitter chat room]: Chat in live with the community on Gitter. + * https://twitter.com/ApacheJames[Twitter]: Express yourself and follow us @ApacheJames. + * https://github.com/apache/james-project[GitHub]: Read and contribute to the source code of the project. + * https://issues.apache.org/jira/projects/JAMES[JIRA]: Report issues or make suggestions for the project on our bug tracker. + * https://builds.apache.org/job/ApacheJames/[CI]: Check the status of James builds on our Jenkins CI. + * xref:download.adoc[Download releases]: Download artifacts and sources your need for the James Server and James libraries. + * xref:support.adoc[Professional support]: Find a list of companies which can provide you some support on James. -We use https://antora.org[Antora] as a tool to manage and generate the website. -We use https://gradle.org[Gradle] as a tool to drive / automate the tasks for generating, aggregating and publishing the website. +== Contribute +James is a project that lives from the contributions of its community. *Anyone can contribute!* -=== Why Antora? +That's right, we always want to hear from people with contributions to the code, the documentation, the website, +and bug reports. We more than welcome non-coding contributions. -Antora lets us aggregate multiple documentation sources, across multiple versions and publish them as a single website. -Documentation for each Apache James component is kept and versioned alongside the code for it. +You can find more information on how to contribute to the James project on the xref:contributing.adoc[contributing] section. -=== Why Gradle? +== Articles for contributors -Gradle allows us to automate the tasks that we do when publishing a website. -We write gradle tasks for building and publishing the website. -We can run those tasks locally and inside our CI infrastructure: https://builds.apache.org[Apache Builds]. +** xref:website.adoc[] +** xref:release.adoc[] -More specifically, we use Gradle to: +== The Apache Software Foundation -* Download and install a specific version of https://nodejs.org[NodeJS] using https://github.com/node-gradle/gradle-node-plugin[Gradle Node Plugin] -* Install a local version of Antora -* Use a Gradle task to call build the website with Antora - -By using this specific flow, you only need `git`, `Java` and shell access to build the website. -All other dependencies are installed automatically by Gradle. -Even Gradle is downloaded and installed using the Gradle wrapper script. - - -== How to build the website - -[source,bash] ----- - # To build the website run - ./gradlew clean build - # The website is located here - cd doc-sites/build/site ----- - - -== How to customize the theme for the documentation - -The documentation website is based on https://antora.org[Antora]. -We have added https://gitlab.com/antora/antora-ui-default/[antora-ui-default] project as a git subtree under `antora-ui`. - -`./gradlew :antora-ui:build` will assemble the `antora-ui/build/ui-bundle.zip` archive required for the website. -All the steps are automated as Gradle tasks in that project. -All you have to do is change the css and html files and then rebuild the project. - -The antora-ui project has a preview mode: `/.gradlew gulpPreviewTheme` - - -[source,shell] ----- - # antora-ui-default was added like this. You should be able to pull some changes from upstream - git subtree add --prefix antora-ui https://gitlab.com/antora/antora-ui-default.git master --squash ----- - - -=== Related links - -* https://medium.com/@v/git-subtrees-a-tutorial-6ff568381844[A git subtree tutorial]. -* https://docs.antora.org/antora/2.3/playbook/configure-ui/[Antora UI keys] +James is a project belonging to the https://www.apache.org/[Apache Software Foundation [ASF\]]. Thus, the Apache Jame project +is governed by a number of xref:guidelines.adoc[guidelines] directly depending on the *ASF*. +If you wish to get more involved with the *ASF* community in general, those links might interest you as well: + * https://www.apache.org/foundation/getinvolved.html[Get involved with the ASF] + * https://www.apache.org/foundation/faq.html[Apache FAQ] + * https://www.apache.org/licenses/[Apache Licenses] + * https://www.apache.org/security/[The Apache security team] + * https://www.apache.org/foundation/sponsorship.html[Sponsorship program] + * https://www.apache.org/foundation/thanks.html[Sponsors list] diff --git a/docs/modules/ROOT/pages/mailing-lists.adoc b/docs/modules/ROOT/pages/mailing-lists.adoc new file mode 100644 index 000000000..5c80196f6 --- /dev/null +++ b/docs/modules/ROOT/pages/mailing-lists.adoc @@ -0,0 +1,162 @@ += Mailing lists + +Please read the <<_guidelines>> below before subscribing to our lists and join our community. + +== James mailing lists + +Most James mailing lists are open and also archived and available online. +You can read them even if you are not subscribed. +You can post only if you are subscribed. + +=== Mailing list archives and web browsing + +You can browse the mailing list archives online using the https://lists.apache.org/list.html?james.apache.org[Pony Mail] instance. + +=== Server user list + +*Low traffic* +mailto:[email protected][Subscribe] +mailto:[email protected][Unsubscribe] +link:++https://lists.apache.org/[email protected]++[Archive] + +This is the list where users of the Apache James (Server) meet and discuss issues. Developers are also expected to be +subscribed to this list to offer support to users of Apache James (Server). + +=== Server developer list + +*Medium traffic* +mailto:[email protected][Subscribe] +mailto:[email protected][Unsubscribe] +link:++https://lists.apache.org/[email protected]++[Archive] + +This is the list where participating developers of the Apache James Project meet and discuss issues, code changes/additions, +etc. Do not send mail to this list with usage questions or configuration problems -- that's what server-user@james is for. + +=== Mime4j + +*Medium traffic* +mailto:[email protected][Subscribe] +mailto:[email protected][Unsubscribe] +link:++https://lists.apache.org/[email protected]++[Archive] + +Discussions on the http://james.apache.org/mime4j[Mime4j] parser library. + +=== James general list + +*Low traffic* +mailto:[email protected][Subscribe] +mailto:[email protected][Unsubscribe] +link:++https://lists.apache.org/[email protected]++[Archive] + +This is the list for general discussions related to the running of the project, it is the public list of the +James project management committee (PMC) and is a public list opened to all. Do not send mail to this list with James +software problems -- that's what server-user@james is for. + +=== Notifications mailing list + +*High traffic* +mailto:[email protected][Subscribe] +mailto:[email protected][Unsubscribe] +link:++https://lists.apache.org/[email protected]++[Archive] + +Subscribers to this list get notices of each and every code change, build results, testing notices, etc. This list is +not for asking help, raising issues or starting discussions on the james product -- other mailing lists are specifically +dedicated to that already. + +== How to unsubscribe your old email address + +First, find out the particular email address to which ezmlm is sending. The email headers are visible in Microsoft Outlook +via the messages menu "View | Options". + + Microsoft Mail Internet Headers Version 2.0 + ... + List-Unsubscribe: <mailto:[email protected]> + List-Help: <mailto:[email protected]> + List-Post: <mailto:[email protected]> + List-Id: "James Server Users List" <server-user.james.apache.org> + Reply-To: "James Server Users List" <[email protected]> + Delivered-To: mailing list [email protected] + ... + Return-Path: [email protected] + ... + +The _Return-Path_ header contains the email address which is subscribed. + +To stop subscription for the address [email protected]_, send an email to + +`server-dev-unsubscribe-john=\[email protected]` + +or to + +`server-user-unsubscribe-john=\[email protected]` + +== Guidelines + +A mailing list is an electronic discussion forum that anyone can subscribe to. When someone sends an email message to +the mailing list, a copy of that message is broadcasted to everyone who is subscribed to that mailing list. +Mailing lists provide a simple and effective communication mechanism for discussion and decision making. + +The *Apache Software Foundation* has well established reasons for using email and not other types of forum. +You may use a mail-news gateway, gmail or anything else you like but email is, and will remain, the official medium. + +With potentially thousands of subscribers, there is a common etiquette that you should observe. Please keep on reading. + +*Respect the mailing list type* + +* "User" lists are lists where you can send questions and comments about configuration, setup, usage and other "user" +types of questions. +* "Developer" lists are lists where you can send questions, comments and contributions about the project's software +source code and general "development" types of questions. + +Some questions are appropriate for posting on both the "user" and the "developer" lists. In this case, pick one and +only one. Do not cross post. + +Asking a configuration question on the developers list is frowned upon because developers' time is as precious as yours. +By contacting them directly instead of the users list you are abusing resources. It is unlikely that you will get a +quicker answer this way, those developers who have time to devote to providing support are also subscribed to the users +list. If you contact individuals directly, or post your user issues to the developer list you may get no answer at all. + +*Join the lists that are appropriate for your discussion* + +Please make sure that you are joining the list that is appropriated for the topic that you would like to discuss. +The general list is for discussions about the management and direction of the James project, not for "general support". + +*Ask smart questions* + +Every volunteer project obtains its strength from the people involved in it. You are welcome to join any of our mailing +lists. You can choose to lurk, or actively participate; it's up to you. The level of community responsiveness to +specific questions is generally directly proportional to the amount of effort you spend formulating your question. +Eric Raymond and Rick Moen have even written an essay entitled "Asking Smart Questions" precisely on this topic. +Although somewhat militant, it is definitely worth reading. + +*Note*: Please do NOT send your Java problems to the two authors. They welcome feedback on the FAQ's contents, but are +simply not a Java help resource. Follow the essay's advice and choose your forum carefully. + +*Keep your email short and to the point* + +If your email is more than about a page of text, chances are that it won't get read by very many people. It is much +better to try to pack a lot of informative information (see above about asking smart questions) into as small of an +email as possible. If you are replying to a previous email only quote the parts that you are replying to and to remove +the unnecessary bits. This makes it easier for people to follow a thread as well as making the email archives easier +to search and read. + +*Do your best to ensure that you are not sending HTML or "Stylelized" email to the list* + +If you are using Outlook or Outlook Express or Eudora, chances are that you are sending HTML email by default. There is +usually a setting that will allow you to send "Plain Text" email. If you are using Microsoft products to send email, +there are several bugs in the software that prevent you from turning off the sending of HTML email. + +*Watch where you are sending email* + +The majority of our mailing lists have set the Reply-To to go back to the list. That means that when you Reply to a +message, it will go to the list and not to the original author directly. The reason is because it helps facilitate +discussion on the list for everyone to benefit from. Be careful of this as sometimes you may intend to reply to a +message directly to someone instead of the entire list. The appropriate contents of the Reply-To header is an age-old +debate that should not be brought up on the mailing lists. You can examine opposing points of view condemning our +convention and condoning it. Bringing this up for debate on a mailing list will add nothing new and is considered off-topic. + +*Do not cross post messages* + +In other words, pick one mailing list and send your messages to that mailing list only. Do not send your messages to +multiple mailing lists. The reason is that people may be subscribed to one list and not to the other. Therefore, some +people will only see part of the conversation. diff --git a/docs/modules/ROOT/pages/release.adoc b/docs/modules/ROOT/pages/release.adoc new file mode 100644 index 000000000..34bbfc9b2 --- /dev/null +++ b/docs/modules/ROOT/pages/release.adoc @@ -0,0 +1,230 @@ += Creating an official Apache James release + +Read details about http://www.apache.org/dev/publishing-maven-artifacts.html[Publishing Maven releases to Maven Central Repository] + +In short, just follow the 'standard' process: + +* prepare pom for release +* publish snapshot +* prepare release +* stage the release for a vote (don't forget to close the staging repository) +* vote +* release + +Don't forget to add your key to https://downloads.apache.org/james/KEYS + + $ ssh people.apache.org + $ cd /www/www.apache.org/dist/james + +== Release cheat sheet + +First, discuss your intention to perform a release on server-dev mailing list, to ensure a consensus would be reached +before starting this time-consuming process. + +Then you can prepare the release materials: + + * Ensure the `CHANGELOG.md` and `upgrade-instructions.md` files are up to date. + * Freeze your version in it and initiate a new iteration. + * Write a blog post within `/src/homepage/_post` about your release. + * Update the documentation website `/docs`, `src/site`, and `README.md` to point to your new release. + * Update the `/dockerfiles` + +Open a pull request to validate the changes. + +=== Running a maven release + +Once merged, it is time for the maven release. + +Set up your maven configuration in `~/.m2/settings.xml` : + +[source,bash] +---- +<settings> + <servers> + <server> + <id>apache.snapshots.https</id> + <username>apacheId</username> + <password>xxxxxx</password> + </server> + <!-- To stage a release of some part of Maven --> + <server> + <id>apache.releases.https</id> + <username>apacheId</username> + <password>xxxxxxxx</password> + </server> + <server> + <id>svn.apache.org</id> + <username>apacheId</username> + <password>xxxxxx</password> + </server> + + </servers> +</settings> +---- + +Ensure that released branch HEAD have a clean green build on the CI. + +Run these commands to perform a release, from the master branch: + +[source,bash] +---- +mvn clean install -DskipTests -Djib.skip -Dmaven.javadoc.skip=true -T 4 + +mvn deploy -DskipTests -Dskip.jib -Dmaven.javadoc.skip=true -T 8 + +mvn release:clean + +mvn release:prepare -Darguments="-Dmaven.javadoc.skip=true -DskipTests -Dskip.jib" -DautoVersionSubmodules=true + +mvn release:perform -Darguments="-Dmaven.javadoc.skip=true -DskipTests -Dskip.jib" -DautoVersionSubmodules=true +---- + +Failure to react when being prompted for git or GPG credentials might abort the release. GPG agent with a reasonable session time can be used to unlock the key before hand and reduce this risk. + +Then visit https://repository.apache.org/#stagingRepositories[Apache maven repository], go in staging repository, close +the corresponding artifact before performing the vote. + +=== Voting procedure + +Send the following voting template on the server-dev mailing list to call the vote: + +[source] +---- +Subject: Call for vote: Apache James x.x.x + +Hi, + +I would like to propose a new vote for x.x.x release of the Apache James server. + +You can find: + + - The maven release staged in repository.apache.org as the +artifact #xxx: +https://repository.apache.org/content/repositories/orgapachejames-xxx/ + - The changelog for +x.x.x: +https://github.com/apache/james-project/blob/master/CHANGELOG.md + - The compatibility instructions/upgrade +recommendation: +https://github.com/apache/james-project/blob/master/upgrade-instructions.md#360-version + +[You can comment on major changes ] + +Voting rules: + - This is a majority approval: this release may not be vetoed. + - A quorum of 3 binding votes is required + - The vote starts at XXXXXX xxxth of xxxxx xxxx, xxxx UTC+x + - The vote ends at XXXXXX xxxth of xxxxx xxxx, xxxx UTC+x + +You can answer to it just with +1 and -1. Down-votes may be motivated. + +3 binding votes are expected move forward on this release. + +Cheers, + +PMC member name +---- + +After the voting period, do the voting aftermaths. Reply in the voting thread: + +[source] +---- +Hi all, + +I am happy to announce you the vote for the x.x.x release did succeed. + +The release received X positive votes, X of them being binding. + +Thanks to all contributors, developers and committers who made this +possible! + +In the coming hours, I will finalize the release process, namely: + +- Publish the maven artifacts +- Upgrade the download page and the (old) website +- Announce the release + +Cheers, + +PMC member name +---- + +=== Convenience downloads for your release + +Clone this SVN repository: `https://dist.apache.org/repos/dist/release/james` + +Create a folder for your release: + +[source] +---- +mkdir server/3.x.x +cd server/3.x.x +svn add . +---- + +Move the release zipped data in this folder: + +- The convenience ZIPs needs to be downloaded from there staged repository. This includes server/app. +- sources can be obtained from GitHub tag + +I use the following script to set up the uploads: + +[source] +---- +% cat /usr/local/bin/auto_sig +#/bin/bash + +# This quick bash scipt intend to help commiters +# preparing artifacts for SVN upload. +# +# Performs: +# - Hashing (sha1 + sha512) +# - Signing (main) +# - Position SVN properties +# +# $1: file to prepare +# $2: Key footprint to use for signing + +sha512sum $1 > $1.sha512 +gpg -u $2 --output $1.asc --detach-sig --armor $1 +svn add $1 +svn propset svn:mime-type application/octet-stream $1 +svn add $1.sha512 +svn add $1.asc +svn propset svn:mime-type application/octet-stream $1.asc +---- + +Once done it is time to commit! `svn commit -m "Upload convenience artifacts for James release 3.x.x"` + +The convenience binaries will then be available. Check that the links of the download page works. + +Cleanup: Only supported release lines should be maintained. Archive the previous release by deleting them from `repos/dist/release` - the INFRA will automatically move them to archive: + +[source] +---- +svn rm 3.5.0 +svn commit -m "Archive James release 3.5.0" +---- + +=== Push docker containers + +WARNING: Docker images are not considered as an official Apache release materials yet the Apache JAMES PMC members decided +to offer their community with a set of maintained docker images, for convenience. + +Docker images includes: + +- apache/james:memory-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/memory-app +- apache/james:jpa-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/jpa-app +- apache/james:demo-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/provisioned-app +- apache/james:cassandra-3.x.x build from https://github.com/apache/james-project/tree/master/server/apps/cassandra-app +- apache/james:distributed-3.x.x built from https://github.com/apache/james-project/tree/master/server/apps/distributed-app + +As a committer contact the INFRA and hand them your docker-hub account to get the permission. + +=== Other steps + +Once done: + + * Deploy website changes + * Send an announce on server-user + * Send an Apache foundation wide announce diff --git a/docs/modules/ROOT/pages/support.adoc b/docs/modules/ROOT/pages/support.adoc new file mode 100644 index 000000000..b9bfae994 --- /dev/null +++ b/docs/modules/ROOT/pages/support.adoc @@ -0,0 +1,28 @@ += Professional support + +Here is a list of companies which can provide you some support on James. + +== Baechler Craftsmanship + +mailto:[email protected][*Baechler Craftsmanship*] has a very strong knowledge both on email and James. The company is +run by a long-time contributor and PMC of James which contributed significant enhancements +over the years. + +The company is committed to contribute to James and offers consultancy for companies willing +to use James on their own infrastructure and/or need enhancements to fit their own needs. + +Free Software is a core value of the company and it can also help customers to work with +James community in an efficient and positive way. + +== Linagora + +image::linagora.png[link=https://linagora.com] + +*Linagora* is an Open Source Software Company. + +Their mission is to bring digital independence to their customers. + +They are focused on large organizations both from private and public sector. They have set themselves the goal of +helping Governments to achieve their digital sovereignty. + +*Linagora* can offer professional services related to James: support, feature development or project integration. diff --git a/docs/modules/ROOT/pages/website.adoc b/docs/modules/ROOT/pages/website.adoc new file mode 100644 index 000000000..6cfdbd50d --- /dev/null +++ b/docs/modules/ROOT/pages/website.adoc @@ -0,0 +1,182 @@ += Building and publishing the website +:path: src/homepage + +The source code of website https://james.apache.org[james.apache.org] is +located in {path}. + +Here are the instructions how to publish new changes to the website. + +The website is currently composed of the output of + +- The homepage build +- The maven site + +[WARNING] +.https://issues.apache.org/jira/browse/JAMES-3187[Documentation migration] +==== +We are migrating the content of the maven site to use xref:_building_the_next_gen_documentation[antora documentation] instead. + +Most of the useful content has been migrated but the new documentation is not +yet published to the main site. It can be found on the +https://james.staged.apache.org[staging version] of the website. +==== + +== Building the homepage + +You can use jekyll to build the website. Go into `{path}` and run the following command + +=== Docker + +[WARNING] +==== +The official docker image `jekyll/jekyll` is unmaintained and is not compatible with jekyll version beyond 4.2.2. +In this documentation we suggest a replacement `jvconseil/jekyll-docker` but note that this is not an official image. +Use at your own risks. +==== + +[source,shell] +---- +$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jvconseil/jekyll-docker:4 jekyll build +---- + +The resulting deployable content will be available in the `{path}/_site/` +directory. + +In order to test the homepage, you can use this command: +[source,shell] +---- +$ docker run --rm -v $PWD/site:/srv/jekyll -p 4000:4000 -it jvconseil/jekyll-docker:4 jekyll serve +---- +The site will be available at http://localhost:4000/ + + +If you need to update the current site, checkout the branch asf-site from +Apache git: +[source,shell] +---- +$ git clone https://git-wip-us.apache.org/repos/asf/james-site.git +$ cd james-site +$ git checkout origin/asf-site -b asf-site +---- + +make sure to build the site then copy the output to + +[source,shell] +---- +$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jvconseil/jekyll-docker:4 jekyll build +$ cp ../james-site/content +---- + +Then just push the new site: +[source,shell] +---- +$ cd ../james-site +$ git push origin asf-site +---- + +=== Experimental nix environment + +From the root of the repository checkout, you can use the flake's devshell + +[source,shell] +---- +$ cd src/homepage +$ nix develop +---- + +Then use jekyll directly + +[source,shell] +---- +$ jekyll serve +# or +$ jekyll build +---- + +==== Gemset update for nix + +Updating the gemset to track the gemfile updates is a bit involved : + +. ensure you are out of all nix devshell (check using `echo $SHLVL` it should be 1) +. create a temporary shell for gem manipulation `nix-shell -p ruby -p bundix` +. update the gemfile then run ++ +[,shell] +---- +BUNDLE_FORCE_RUBY_PLATFORM="true" bundle lock --update +bundix -l +---- +. exit the temporary shell and enter the devShell again `nix develop` + +== Maven site + +The maven site deploy phase uses and requires locally configuring credentials to +enable ssh access. See +http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html[maven-deploy-plugin's documentation] for more details on achieving this. + +WARNING: Generating the full maven site with all reports takes a long time +(as in hours) + +=== Manually + +1. Install Apache Maven 3.0.2+ and make its binary 'mvn' available on your PATH. +See http://maven.apache.org/download.html#Installation. +2. run `mvn clean package site -Djib.skip` +3. Test the built site in your browser from the `{path}/target/site` folder +4. If everything looks OK, deploy the site using `mvn clean site-deploy`. +5. Wait for the changes to replicate to the Apache web server or setup +140.211.11.10:80 as a proxy to review the changes (described here: +http://www.apache.org/dev/project-site.html) + +=== Docker + +Can be used only to build the site locally + +[WARNING] +.Contribution welcome +==== +The docker file in `src/site-docker` is currently broken: + +- outdated JDK (11 instead of 21) +- "manual" download of maven from a link which doesn't resolve anymore + +prepare for some tinkering before building using this method. +==== + +[source,shell] +---- +$ docker build -t james/site src/site-docker +$ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination james/site master +---- + +=== Nix development shell + +Enter the xref:contributing.adoc#_experimental_nix_support[james experimental +development shell] with `nix develop`. + +1. run `mvn clean package site -Djib.skip` +2. Test the built site in your browser from the `{path}/target/site` folder +3. If everything looks OK, deploy the site using `mvn clean site-deploy`. +4. Wait for the changes to replicate to the Apache web server or setup +140.211.11.10:80 as a proxy to review the changes +(see: http://www.apache.org/dev/project-site.html) + +=== Technical reports + +To deploy the technical reports use any of the 3 ways above adding the +`-Psite-reports` profile. + +== Building the next gen documentation + +The old maven site is quite painful to maintain and doesn't allow for +versionning of the content per releases which motivated the +https://issues.apache.org/jira/browse/JAMES-3187[migration effort]. + +Most of the maven site content has been migrated to asciidoc files assembled by +antora. You can preview the content at https://james.staged.apache.org, this +documentation is published automatically by the james CI. + +This new documentation root is located in the `docs` directory and includes +these build instructions. + +include::partial$antora.adoc[] diff --git a/docs/modules/ROOT/partials/antora.adoc b/docs/modules/ROOT/partials/antora.adoc new file mode 100644 index 000000000..69a03a8b6 --- /dev/null +++ b/docs/modules/ROOT/partials/antora.adoc @@ -0,0 +1,60 @@ +== Building the next gen documentation +:page-partial: + +The old maven site is quite painful to maintain and doesn't allow for +versionning of the content per releases which motivated the +https://issues.apache.org/jira/browse/JAMES-3187[migration effort]. + +Most of the maven site content has been migrated to asciidoc files assembled by +antora. You can preview the content at https://james.staged.apache.org, this +documentation is published automatically by the james CI. + +This new documentation root is located in the `docs` directory and includes +these build instructions. + +=== Executing within source code + +(Clone `https://github.com/apache/james-project` locally, go into `docs` folder) + +. https://docs.antora.org/antora/latest/install-and-run-quickstart/[Install Antora] + +. Build the Antora content locally ++ +[,shell] +---- + $ antora antora-playbook-local.yml +---- ++ +. Open `build/site/index.html` in your browser. + +=== Building with Dockerfile + +To build the document from apache-james repository, you can use the Dockerfile provided in this folder. + +Build the Docker image: + +---- +docker build --build-arg JAMES_CHECKOUT=master -f Dockerfile -t james-site-antora . +---- + +Then run the Docker image: + +---- +docker run -p 80:80 james-site-antora +---- + +Go to `http://localhost` in your browser. + +=== Build with the nix enviroment + +Enter the xref:contributing.adoc#_experimental_nix_support[james experimental +development shell] with `nix develop` + +. Build the Antora content locally ++ +[,shell] +---- + $ antora antora-playbook-local.yml +---- ++ +. Open `build/site/index.html` in your browser. \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
