| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-section"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>Committer how-to - Apache FreeMarker™</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="Apache FreeMarker™"> |
| <meta property="og:title" content="Committer how-to"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/committer-howto.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/committer-howto.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707809060700"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/"> |
| <meta itemprop="name" content="Apache FreeMarker™"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org/" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li class="current"><a href="index.html">Home</a></li><li><a href="docs/index.html">Manual</a></li><li><a class="external" href="docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["Apache FreeMarker™","Community","Committer how-to"];</script> |
| <script src="toc.js?1707809060700"></script> |
| <script src="docgen-resources/main.min.js?1707809060700"></script> |
| <div class="side-toc-logos"> |
| <div class="side-toc-logo"> |
| <a href="https://www.apache.org/events/current-event.html" target="_blank"><img src="https://www.apache.org/events/current-event-234x60.png" alt="Apache Incubator" /></a> |
| </div> |
| </div> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="committer-howto" itemprop="headline">Committer how-to</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#git-commit-policy" data-menu-target="git-commit-policy">Git commit policies</a></li><li><a class="page-menu-link" href="#merging-pull-request" data-menu-target="merging-pull-request">Merging in pull requests from GitHub</a></li><li><a class="page-menu-link" href="#close-pull-request-without-merging" data-menu-target="close-pull-request-without-merging">Closing GitHub pull requests without merging</a></li><li><a class="page-menu-link" href="#making-releases" data-menu-target="making-releases">Making releases</a></li><li><a class="page-menu-link" href="#deploy-snapshot" data-menu-target="deploy-snapshot">Deploying Maven SNAPSHOT versions</a></li><li><a class="page-menu-link" href="#updating-homepage" data-menu-target="updating-homepage">Updating the FreeMarker home page</a></li><li><a class="page-menu-link" href="#updating-docgen" data-menu-target="updating-docgen">Updating Docgen</a></li><li><a class="page-menu-link" href="#edit-docbook" data-menu-target="edit-docbook">Regarding editing the Manual and the Site DocBook</a></li><li><a class="page-menu-link" href="#handle-security-vulnerabilities" data-menu-target="handle-security-vulnerabilities">Dealing with security vulnerabilities</a></li><li><a class="page-menu-link" href="#pmc-resources" data-menu-target="pmc-resources">PMC member resources</a></li></ul> </div><p><em>This page applies to Committers only, not to usual |
| contributors.</em> A Committer is a person with extra rights who |
| receives his or her status via invitation. You don't need to be a |
| Committer to contribute, anyone can fork and send pull requests on |
| Github; see more on <a href="contribute.html">the page for |
| contributors</a>.</p> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="git-commit-policy">Git commit policies</h2> |
| |
| |
| <p>Committers can commit directly into the Apache Git repository of |
| FreeMarker, and so preferably don't use GitHub pull requests. (See |
| <a href="sourcecode.html">the repositories and branches |
| here</a>.)</p> |
| |
| <p>Committers have the technical permissions to commit directly |
| into the "main" branch (or branches), and they are |
| expected to use that wisely. Depending on the complexity of the |
| feature, the number of active Committers in the time period, and |
| whether the feature is experimental, they may should work in a feature |
| branch instead. If the feature is finished and discussions were |
| resolved (on some way described by Apache policies), it can be merged |
| back into the "main" branch.</p> |
| |
| <p>All commits should have helpful comments; don't be afraid of |
| writing long descriptions. If the commit is related to a Jira issue, |
| the comment should start with the Jira issue identifier, like |
| "FREEMARKER-16: ..."</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="merging-pull-request">Merging in pull requests from GitHub</h2> |
| |
| |
| <p>Pull requests from GitHub are merged in by Committers. Before |
| accepting a pull request, ensure that:</p> |
| |
| <ul> |
| <li> |
| <p>You have checked all the changes. In particular, the files |
| (with a few exceptions like the <code class="inline-code">README.md</code>) must |
| have the standard Apache copyright headers, and must not state |
| that they have a different license.</p> |
| </li> |
| |
| <li> |
| <p>The contributor has an ICLA or CCLA at Apache (see on <a href="http://people.apache.org/">http://people.apache.org/</a>). |
| If not, the pull request can be merged only if the commit only did |
| trivial changes (like fixing typos) that would be easy to |
| replicate in case legal issues are raised later. In particular, |
| new files added is a sign that ICLA/CCLA will be needed.</p> |
| </li> |
| |
| <li> |
| <p>The contributor has used the proper branch of the project |
| (it's sometimes overlooked)</p> |
| </li> |
| </ul> |
| |
| <p>The commit comment should automatically describe that it's a |
| merge and where it was merged from. After that you may also want to |
| add a summary of what the merged branch does. In general, pull request |
| merge commits should adhere to the same policies that Committers use |
| to commit directly into the Apache git repository.</p> |
| |
| <p>To do the actual merging, if your Apache and Github accounts are |
| linked (see how on the <a href="https://gitbox.apache.org/">ASF Writable Git Services |
| homepage</a>), the Merge (and Close) button on Github should appear |
| and work.</p> |
| |
| <p>If you can't/don't want to use Github, use this command on your |
| clone of the Apache repo (not the Github repo) (need to be tested if |
| it still works after the migration to Gitbox):</p> |
| |
| |
| |
| <div class="code-block role-default"> |
| <pre class="code-block-body">git pull --no-ff https://github.com/apache/<PROJECT> refs/pull/<PR_NUMBER>/head</pre> </div> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code"> <em class="code-color"><PROJECT></em> |
| </code>is usually <code class="inline-code">freemarker</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"> <em class="code-color"><PR_NUMBER></em> |
| </code>is the pull request number that GitHub shows prominently |
| after a "#"</p> |
| </li> |
| </ul> |
| |
| <p>Pushing such a merge commit to the ASF repo will automatically |
| close the pull request on Github.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="close-pull-request-without-merging">Closing GitHub pull requests without merging</h2> |
| |
| |
| <p>You should state the reason of closing in the closing |
| comment.</p> |
| |
| <p>Yet again, if your Apache and Github accounts are linked, the |
| Close button on Github should appear and work.</p> |
| |
| <p>Without linked accounts, we used this command on the clone of |
| the Apache repo (but apparently it doesn't work on non-master branch |
| anymore):</p> |
| |
| |
| |
| <div class="code-block role-default"> |
| <pre class="code-block-body">git commit --allow-empty -m "closes apache/<PROJECT>#<PR_NUMBER>: <WHY>"</pre> </div> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code"> <em class="code-color"><PROJECT></em> |
| </code>is usually <code class="inline-code">freemarker</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"> <em class="code-color"><PR_NUMBER></em> |
| </code>is the pull request number that GitHub shows prominently |
| after a "#"</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code"> <em class="code-color"><WHY></em> |
| </code>is the reason of the closing. For clarity, you may want |
| to end it with "Closed PR without merging." or |
| something similar.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="making-releases">Making releases</h2> |
| |
| |
| <p>For each release, one of the Committers takes on the role of |
| Release Manager. The Release Manager should follow the procedure here, |
| and should update this page where they has to deviate from it.</p> |
| |
| <p>For general info about making releases, please read <a href="https://www.apache.org/legal/release-policy#archived">https://www.apache.org/legal/release-policy</a>. |
| The FreeMarker-specific additions to those are:</p> |
| |
| <ul> |
| <li> |
| <p>The official release is provided as source code to build the |
| project (src tar.gz). For the convenience of users the release is |
| also accompanied by compiled binaries (bin tar.gz, which also |
| contains the documentation). Both artifacts are downloadable from |
| the Apache Software Foundation, as usual.</p> |
| </li> |
| |
| <li> |
| <p>Releases should have a usual jar artifact, an src artifact |
| and javadoc artifact either in the Apache Maven staging repository |
| (for RC-s), or in the Maven Central Repository (for |
| finals).</p> |
| </li> |
| |
| <li> |
| <p>In the 2.3.x branch, we release two products, the normal and |
| the GAE (Google App Engine) version. Hence when executing the |
| release steps, you do many of them twice. Note that source code |
| changes should be made in the 2.3-gae branch, and then merged into |
| the 2.3 branch (unless a change only applies to 2.3).</p> |
| </li> |
| |
| <li> |
| <p>Releases with deeper changes sometimes should have one or |
| more Release Candidate releases (RC01, RC02, etc.), which is |
| legally a normal release (not just a internal/developer one), and |
| is promoted on our web page. The differences to a final release |
| are these:</p> |
| |
| <ul> |
| <li> |
| <p>RC-s aren't released to the Maven Central Repository, |
| only to the Apache Maven repository</p> |
| </li> |
| |
| <li> |
| <p>RC documentation (Manual + JavaDoc) is only published |
| under |
| https://freemarker.apache.org/builds/<em>X.X.X</em>-rc<em>X</em>/</p> |
| </li> |
| |
| <li> |
| <p>RC-s promise no backward compatibility for the new |
| features they add; they may be redesigned or dropped till the |
| final release comes out.</p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>The steps of making a release:</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>Check that <code class="inline-code">version.properties</code> is up to |
| date.</p> |
| </li> |
| |
| <li> |
| <p>Ensure that the version number in the title and version |
| history of the Manual is up to date. Also the release date Version |
| history section of the Manual has to be updated. That's tricky as |
| you can't know it exactly, yet you can't change it when the actual |
| release is about to happen, as that would change the release |
| artifacts that were voted upon. So write the current date and |
| "+ release process" after it; that's how it will be |
| in the released artifacts.</p> |
| </li> |
| |
| <li> |
| <p>Ensure that all changes in the 2.3-gae branch were merged |
| into the 2.3 branch. (Also that both branches where <code class="inline-code">git |
| push</code>-ed.)</p> |
| </li> |
| |
| <li> |
| <p>Do a clean checkout of the branch to release, just to ensure |
| that you won't include any files temporary files that you put |
| there during development. Work in that checkout from now on. Don't |
| forget to create the <code class="inline-code">build.properties</code> in |
| it.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ant dist</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ant rat</code>, check output. There can't be any |
| binaries, archives, and especially not unknown or unapproved |
| licenses in the reports. Skip to the next point if there were |
| none! Otherwise, check if the problematic files are fine legally. |
| If they weren't produced in this project, add them to the related |
| <code class="inline-code">LICENSE</code> files (there are several of them, |
| depending on if it's for the source, the binary distribution, the |
| Maven jar artifact, or the Maven javadoc artifact). You also have |
| to add them to the related <code class="inline-code">rat-excludes</code> file |
| (there's one in the project root for the source release, and |
| another in <code class="inline-code">src/dist/bin</code> for the binary release) |
| so that the files won't be reported next time. Note that |
| <code class="inline-code">rat-exludes</code> should contain a comment that |
| clarifies the origin of the files. Finally restart the process |
| from rebuilding the distribution.</p> |
| </li> |
| |
| <li> |
| <p>Compare the jar to the earlier stable release for API |
| compatibility issues (both source and binary level). So far we |
| have used <a href="https://lvc.github.io/japi-compliance-checker/">"Java |
| API Compliance Checker" (JAPICC)</a> with these |
| arguments: <code class="inline-code">-keep-internal -skip-internal-types \._ -l |
| FreeMarker <em class="code-color">old</em>.jar |
| <em class="code-color">new</em>.jar</code>. Note that it's prone |
| to generate false alarms, so simply review each problems and |
| decide which is real.</p> |
| </li> |
| |
| <li> |
| <p>Ensure that this is up to date: |
| https://dist.apache.org/repos/dist/<em>{dev,release}</em>/freemarker/KEYS</p> |
| </li> |
| |
| <li> |
| <p>SVN commit the release files into the proper subdirectory of |
| https://dist.apache.org/repos/dist/<strong>dev</strong>/freemarker. Note that this is |
| "dev/", not "release/"! You will likely |
| find the "dev" directory empty, so see the proper |
| layout under the "release" directory as a sample, but |
| don't commit to there accidentally.</p> |
| </li> |
| |
| <li> |
| <p>Upload to ASF Nexus staging</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>If your Maven <code class="inline-code">settings-security.xml</code> |
| is relocated to an encrypted storage (recommended), mount it, |
| otherwise you will get 401 error when uploading. (How that's |
| done: create a file called settings-security.xml next to |
| ~/.m2/settings.xml, with content |
| <code class="inline-code"><settingsSecurity><relocation><em class="code-color">your-decrypted-storage-mount</em>/settings-security.xml</relocation></settingsSecurity></code>)</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">ant maven-dist</code></p> |
| </li> |
| |
| <li> |
| <p>Go to <a href="https://repository.apache.org/">https://repository.apache.org/</a>, |
| log in, chose "Staging Repositories", find and |
| click the repository just created. Check the upload files |
| manually (on the "Content" tab). Then |
| "Close" the repository. Press |
| "Refresh" until it's successfully |
| "closed". (Be careful, do NOT |
| "Release"!)</p> |
| </li> |
| </ol></div> |
| </li> |
| |
| <li> |
| <p>Upload the content <em>inside</em> |
| <code class="inline-code">documentation/_html</code> from the binary release to |
| https://freemarker.apache.org/<strong>builds/<em>X.X.X</em>-voting</strong>/ |
| (by committing it into the "asf-site" branch of |
| https://git-wip-us.apache.org/repos/asf/freemarker-site.git). The |
| change log will be a link pointing to a page inside this.</p> |
| </li> |
| |
| <li> |
| <p>Voting on the FreeMarker developer list</p> |
| |
| <div class="orderedlist"><ol type="1"> |
| <li> |
| <p>Start a thread on the FreeMarker developer mailing list |
| with subject "[VOTE] Release Apache FreeMarker |
| <em>X.X.X</em>". You should use an |
| earlier release vote mail as a template. Some notes:</p> |
| |
| <ul> |
| <li> |
| <p>Use your apache.org e-mail address as the |
| sender</p> |
| </li> |
| |
| <li> |
| <p>Link artifacts. The src artifact is the release |
| that's voted upon. The bin is for convenience only, though |
| of course still need to be checked.</p> |
| </li> |
| |
| <li> |
| <p>Include and link via the Git commit |
| <em>hash</em> (not a tag)</p> |
| </li> |
| |
| <li> |
| <p>Link the change log (page under |
| https://freemarker.apache.org/builds/<em>X.X.X</em>-voting/)</p> |
| </li> |
| |
| <li> |
| <p>Specify Maven staging repository URL and artifact |
| coordinates, also the URL of the repository directory that |
| contains this release for easier reviewing</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Needs at least 3 "+1" votes from FreeMarker |
| PMC members, majority win, and minimum 72 hours (but see |
| Apache policies). Generally, we wait more, so that more people |
| can test there release.</p> |
| </li> |
| |
| <li> |
| <p>Post "[RESULT][VOTE]" mail to the |
| FreeMarker developer list. Again, you should use an earlier |
| release vote result mail as a template.</p> |
| </li> |
| |
| <li> |
| <p>If it was a failed vote, after fixing the issues, the |
| release process restarts with a different dist.apache.org |
| URL-s (add an attempt number to the directory for |
| example)</p> |
| </li> |
| </ol></div> |
| </li> |
| |
| <li> |
| <p>Copy the release files over from |
| https://dist.apache.org/repos/dist/<strong>dev</strong>/freemarker into the proper subdirectory |
| of https://dist.apache.org/repos/dist/<strong>release</strong>/freemarker and commit them. (Of |
| course get rid of any voting attempt numbers in the directory |
| names.) After a few minutes of delay, they should appear under |
| <a href="https://www.apache.org/dist/freemarker/">https://www.apache.org/dist/freemarker/</a>.</p> |
| </li> |
| |
| <li> |
| <p>Go to <a href="https://repository.apache.org/">https://repository.apache.org/</a> |
| and find the staging repository that belongs to the voted version. |
| Select it, press "Release" at the top. Now the |
| repository should appear under <a href="https://repository.apache.org/content/repositories/releases/org/freemarker/">https://repository.apache.org/content/repositories/releases/org/freemarker/</a> |
| Later (like hours later) it will appear in the Maven Central |
| Repository too.</p> |
| </li> |
| |
| <li> |
| <p>Tag the release on Git (tags are like |
| <code class="inline-code">v2.3.45-gae</code> and <code class="inline-code">v2.3.45</code>). Be |
| careful not to tag a commit made since the voting has |
| succeeded.</p> |
| </li> |
| |
| <li> |
| <p>Add the release on: <a href="https://reporter.apache.org/addrelease.html?freemarker">https://reporter.apache.org/addrelease.html?freemarker</a></p> |
| </li> |
| |
| <li> |
| <p>Update <code class="inline-code">doap.rdf</code> in the |
| <code class="inline-code">freemarker-site</code> repository, by adding a new |
| <code class="inline-code">release</code> element. Don't forget to commit it into |
| the <code class="inline-code">asf-site</code> branch as well, not just into |
| <code class="inline-code">master</code>, or else it's not published.</p> |
| </li> |
| |
| <li> |
| <p>Wait 24 hours so that the mirrors get synced. Check <a href="https://www.apache.org/dist/freemarker/">https://www.apache.org/dist/freemarker/</a> |
| and <a href="http://archive.apache.org/dist/freemarker/">http://archive.apache.org/dist/freemarker/</a>. |
| Check Maven Central repository too (in the case of non-RC |
| releases).</p> |
| </li> |
| |
| <li> |
| <p>Delete the non-latest release of each maintained branch from |
| https://www.apache.org/dist/freemarker/ (Old ones are |
| automatically available on http://archive.apache.org/dist/)</p> |
| </li> |
| |
| <li> |
| <p>Update https://freemarker.apache.org:</p> |
| |
| <ul> |
| <li> |
| <p>Upload latest JavaDoc</p> |
| </li> |
| |
| <li> |
| <p>Update release date in the Manual in the Version history |
| (now that we know it), then generate the Manual with |
| <code class="inline-code">ant manualOnline</code>.</p> |
| </li> |
| |
| <li> |
| <p>Upload the new Manual (the online version you have |
| generated in the last step, not the offline one)</p> |
| </li> |
| |
| <li> |
| <p>Update to latest release in the download section</p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Update other web pages:</p> |
| |
| <ul> |
| <li> |
| <p>Update <a href="https://en.wikipedia.org/wiki/FreeMarker">https://en.wikipedia.org/wiki/FreeMarker</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Announce:</p> |
| |
| <ul> |
| <li> |
| <p>On the FreeMarker developer list</p> |
| </li> |
| |
| <li> |
| <p>On announce@apache.org (see <a href="https://lists.apache.org/list.html?announce@apache.org">https://lists.apache.org/list.html?announce@apache.org</a> |
| for examples).</p> |
| </li> |
| |
| <li> |
| <p>On <a href="https://twitter.com/freemarker">https://twitter.com/freemarker</a></p> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>Close issues on Jira that were resolved by this release (the |
| Version history in the Manual should contain links to them)</p> |
| </li> |
| |
| <li> |
| <p>Update try.freemarker.apache.org to use the latest |
| FreeMarker version. About the deployment, see more <a href="https://cwiki.apache.org/confluence/display/FREEMARKER/try.freemarker.apache.org+maintenance+and+installation">here...</a></p> |
| </li> |
| |
| <li> |
| <p>If the release has introduced new syntax or built-ins or |
| directives, the FreeMarker dependency of JBoss Tools FreeMarker |
| IDE must be updated. As JBoss has stopped maintaining that plugin, |
| currently we are maintaining a <a href="https://github.com/jbosstools/jbosstools-freemarker">https://github.com/jbosstools/jbosstools-freemarker</a> |
| fork for this.</p> |
| </li> |
| </ol></div> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="deploy-snapshot">Deploying Maven SNAPSHOT versions</h2> |
| |
| |
| <p>After you have merged/committed your changes to the respectable |
| branch, you may want to publish that version to <a href="https://repository.apache.org/content/repositories/snapshots">https://repository.apache.org/content/repositories/snapshots</a>. |
| Users or fellow developers can use this Maven repository to try |
| snapshot versions.</p> |
| |
| <p>To publish the snapshot version, fist check that |
| <code class="inline-code">version.properties</code> contains the proper version, |
| most importantly, that <code class="inline-code">mavenVersion</code> ends with |
| <code class="inline-code">-SNAPSHOT</code>. (If not, it will deploy to the release |
| staging repository.) Then issue <code class="inline-code">ant dist |
| maven-dist</code>. (Note that just as with a real release, the |
| artifacts will be signed with PGP.)</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="updating-homepage">Updating the FreeMarker home page</h2> |
| |
| |
| <p>The content of the home page can be changed by committing it |
| into the <code class="inline-code">asf-site</code> branch of the |
| <code class="inline-code">freemarker-site</code> repository. However, you shouldn't |
| directly edit the content of most HTML files there, as pretty much all |
| of them are generated, and then is just manually copied over there. |
| The generated pieces are:</p> |
| |
| <ul> |
| <li> |
| <p>The contents of the <code class="inline-code">docs/api</code> is generated |
| from the <code class="inline-code">freemarker</code> project, by issuing |
| <code class="inline-code">ant javadoc</code> there (not in the |
| <code class="inline-code">site</code> project). So to change the content, you |
| should edit the documentation comments in the java files.</p> |
| </li> |
| |
| <li> |
| <p>The contents of <code class="inline-code">docs/</code> is generated from |
| the <code class="inline-code">freemarker</code> project, by issuing <code class="inline-code">ant |
| manualOnline</code>. So to change the content, you should edit |
| <code class="inline-code"><em class="code-color"><freemarker-project></em>/src/manual/en_US/book.xml</code>.</p> |
| </li> |
| |
| <li> |
| <p>Most other content is generated from the |
| <code class="inline-code">site</code> project, by issuing <code class="inline-code">mvn -U |
| package</code>. So to change the content, you should edit |
| <code class="inline-code"><em class="code-color"><site-project></em>/src/main/docgen/book.xml</code> |
| (in the <code class="inline-code">master</code> branch, not in the |
| <code class="inline-code">asf-site</code> branch).</p> |
| </li> |
| </ul> |
| |
| <p>After you commit into the <code class="inline-code">asf-site</code> branch of |
| the <code class="inline-code">freemarker-site</code> repository, it will |
| automatically appear on the web site, with some small delay (a few |
| seconds usually). If it doesn't, that's probably because of a known |
| infrastructural glitch, where for too big commits this synchronization |
| doesn't happen. In such case, commit some small change to trigger |
| synchronization again.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="updating-docgen">Updating Docgen</h2> |
| |
| |
| <p>Docgen (<code class="inline-code">freemarker-docgen</code> Git repository) |
| generates HTML from a DocBook XML. It's a dependency of FreeMarker |
| binary release building (as that contains the Manual in HTML format) |
| and of <code class="inline-code">freemarker-site</code>.</p> |
| |
| <p>Docgen is not published to the Maven Central Repository (yet?), |
| only into the Apache Maven Snapshot Repository. That works for us |
| because it's an internal build dependency, and the dependent projects |
| are set up to find it in the Apache Maven Snapshot Repository. If you |
| modify Docgen, just issue <code class="inline-code">mvn deploy</code> to make the |
| new version available for the later dependent builds.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="edit-docbook">Regarding editing the Manual and the Site DocBook</h2> |
| |
| |
| <p>Both the site and the Manual is generated from the XML files |
| (DocBook format) by the custom Ant task defined in the |
| <code class="inline-code">docgen</code> project |
| (<code class="inline-code">freemarker-docgen</code> repository). That project also |
| provides an XMLMind XML Editor (XXE for short) addon for editing these |
| files. For more guide lines see |
| <code class="inline-code">src/manual/en_US/docgen-help/editors-readme.txt</code> in |
| the <code class="inline-code">freemarker</code> repository. About the same guide |
| lines apply to the site DocBook as well.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="handle-security-vulnerabilities">Dealing with security vulnerabilities</h2> |
| |
| |
| <p>If someone reports a security vulnerability, normally they |
| shouldn't do it on a public forum (<a href="report-security-vulnerabilities.html">see how to report it |
| here</a>), and similarly we shouldn't discuss it on a public forum |
| (such as on the developer mailing list), but on the private mailing |
| list of the project. Thus the vulnerability can be fixed and released |
| before it's openly discussed. As a developer, you must not forget that |
| commits are also publicly visible. How to commit, release, and |
| communicate a concrete vulnerability should be discussed on the |
| private mailing lists of the project before doing publicly visible |
| moves. See <a href="https://www.apache.org/security/committers.html">this |
| page</a> for further guidelines.</p> |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="pmc-resources">PMC member resources</h2> |
| |
| |
| <p>This section is for PMC (Project Management Committee) members |
| only, and meant to contain information that is specific to the |
| FreeMarker project.</p> |
| |
| <p>To share files among PMC members (such as Board report drafts), |
| use this SVN repository: <a href="https://svn.apache.org/repos/private/pmc/freemarker/">https://svn.apache.org/repos/private/pmc/freemarker/</a>. |
| It can be read by PMC members only.</p> |
| </div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="index.html">What is FreeMarker?</a></li><li><a href="freemarkerdownload.html">Download</a></li><li><a href="docs/app_versions.html">Version history</a></li><li><a href="docs/app_faq.html">FAQ</a></li><li><a itemprop="license" href="docs/app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="docs/dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="docs/ref_directive_alphaidx.html">#directives</a></li><li><a href="docs/ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="docs/ref_specvar.html">.special_vars</a></li><li><a href="docs/api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">GitHub</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2024-02-13T07:24:20Z" title="Tuesday, February 13, 2024 at 7:24:20 AM Greenwich Mean Time">2024-02-13 07:24:20 GMT</time> </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
