The JavaCC Eclipse Plug-in administrator guide

Overview

This document is for project admins and describes the different steps to make a new release and update the update site.

Version

Last update June, 2023 - version 1.6.0 (refactored in a markdown document)

How to set up the admin & security requirements for the JavaCC Eclipse Plugin update site at SourceForge

Nov 22th, 2009 / Jun 2023

• User must be granted admin rights through the project admin site (Project Admin / Membership)
• User must generate on his workstation a pair of DSA or RSA keys
  • e.g.: through Eclipse Window / Preferences / General / Network Connections / SSH2 / Key Management / Generate DSA Keys
  • user must choose (and record) a pass phrase and save the keys on his workstation (e.g. save private key under xxx.txt and public key under xxx.txt.pub; they will be in OpenSSH format)
• User must upload his public key to the SourceForge (SF) site (through Account / Services / Edit SSH Keys for Shell/CVS and paste; the update may take some delay)
• To use PSFTP or WinSCP the files must be in Putty keys format, so use puttygen to load the keys (from xxx.txt) and save the private key to xxx.ppk and the public key to xxx.ppk.pub

How to create the JavaCC Eclipse Plugin update site jar files

Nov 22th 2009 / Feb 17th 2010 / Feb 25th 2010 / Mar 31th 2010 / Jun 29th 2012, Sept 26th 2012, Dec 30th 2014, Apr 2016, Dec 2020, Apr-Jun 2023

Ensure you are using an Eclipse version running on a JDK <=11, not 17 (see Bugzilla #572034), so for me Neon is the current choice.

Overview

When the export is done with as the Destination:

• the 1st choice Directory: it allows to sign jars and to categorize the features and it creates in the given folder the features/*.jar, plugins/*.jar, artifacts.jar & (categorized) content.jar; the 4 files can be uploaded to the update site; the Eclipse Installer finds (in a Local site referring to the directory or in the remote update site) the features under a category

• the 2nd choice Archive file: it allows to sign jars and to categorize the features and it creates the given zip file containing the features/*.jar, plugins/*.jar, artifacts.jar & (categorized) content.jar; if only the zip file is uploaded to the update site the Eclipse Installer does find in an Archive site referring to the zip file the features, but does not find in the remote site the features, so for this case the 2 jars must be extracted and uploaded too the update site

• the 3rd choice Install into host Repository: it allows to sign jars but not to categorize the features and it creates in the given folder the features/*.jar, plugins/*.jar, artifacts.jar & (uncategorized) content.jar; the 4 files can be uploaded to the update site; the Eclipse Installer finds (in the remote site) the features (if the Group items by category checkbox is unchecked)

For versions 1.5.xx, we used the export wizard on each 2 (normal & headless) features with the archive file choice on 2 different zip files, then the Build All button on each of the 2 site.xml (producing the plugins/features/artefacts jars), uploaded all the files and directories; there were too many manual steps. We found a more simplified way.

So starting with versions 1.6.0 we restructured the plug-ins / features / update site, and we use the export wizard on all the 3 features with the directory choice for the version and that is all; then we upload the 2 directories and the 2 jars to the update site, and we create local sites instead of archive sites for local testing.

1 - Check / update the documents in all the projects

• Check / update the .md / .textile / .txt in all the projects, then Build all the projects:
  • either automatically (because they have their ant builders enabled),
  • or if not by manually building it through the build_<prj>_html.xml script
• In particular, in project sf.eclipse.javacc.feature:
  • update .md documents: site/README_Site, site/doc/a_faire_plugin.txt, site/doc/Release_notes/README_Release_notes, site/doc/Admin_guide/README_Admin_guide and projects readme descriptions.
• Update JTB Project, check that Release_Notes.txt and jtb_doc.html are up to date
  • see build.xml
  • update documents

2 - Update the projects versions

• Update project sf.eclipse.javacc.help:

  • update the version (x.y.z) in plugin.xml
  • check dependencies
  • check the Runtime Exported Packages
  • (do not use the Export Wizard)

• Update project sf.eclipse.javacc.core:

  • copy jtb-t.u.v.jar under the jars folder
  • update JavaCC & JTB jar names and versions in plugin.properties and plugin_fr.properties
  • review plugin.xml (change / add JavaCC / JTB jar names in build.properties tab)
  • update the version in plugin.xml
  • check dependencies
  • check the Runtime Exported Packages
  • (do not use the Export Wizard)

• Update project sf.eclipse.javacc.ui:

  • update the version in plugin.xml
  • check dependencies (specially the version for the Core plug-in)
  • update dependencies if dropping support of some Eclipse version
    (Note: take care in using the Find unused dependencies):
    the org.eclipse.debug.ui is needed for the import org.eclipse.debug.ui.StringVariableSelectionDialog in GlobalOptions.java,
    and seems to make the org.eclipse.core.resources unused, although it is used in NewGrammarWizardPage.java;
    also the org.eclipse.e4.ui.workbench.renderers.swt has been added although unused for the windows 32b or 64b fragments)
  • check the Runtime Exported Packages
  • (do not use the Export Wizard)

• Update project sf.eclipse.javacc.help.feature through feature.xml:

  • update the version
  • check and (re)compute the dependencies
  • (do not use the Export Wizard)

• Update project sf.eclipse.javacc.headless.feature through feature.xml:

  • update the version
  • check and (re)compute the dependencies
  • (do not use the Export Wizard)

• Update project sf.eclipse.javacc.feature:

  • create the new sub-folder x.y.z under releases
  • in feature.xml:
  • update the version
  • check and (re)compute the dependencies
  • in category.xml:
  • in Category Definition tab add new version features (keep them in the category), remove old version features

3 - Export all the features to a p2 repository format:

• Check / set the version in site\build_updatesite_zip.xml
• Use delete_jars in the previous script each time you want to re-export the features
• Use File / Export / Deployable features
  • select all 3 features
  • set (update) in Destination tab the destination to a directory ...\sf-eclipse-javacc-plugin\sf.eclipse.javacc.feature\site\releases\x.y.z
  • set (check) in the Options tab:
    • Package as individual jar archives
    • Generate p2 repository
    • Categorize repository : Browse to the site\category.xml file
    • Allow for binaries cycles in the target platform
  • set (check) in the Jar Signing tab:
    • Sign the jar ...
    • all other settings (the keystore has been initialized with the script gen_keystore.cmd)
  • and run
• Check the new zip installs well (new installation or update installation, from Neon to last installation, with a local site set to the release version directory)

4 - Upload the update site files to the SF site

• Use make_zip in the site\build_updatesite_zip.xml to create a zip file of the release version directory site\releases\x.y.z (-> sf.eclipse.javacc-x.y.z-updatesite.zip)
• Upload the release version directory site\releases\x.y.z to the corresponding folder htdocs/x.y.z of the update site
• Create a new remote software site pointing to this version folder and check it installs well
• Copy the contents of this folder htdocs/x.y.z to the root of the update site htdocs when ready to publish the release
• See below

5 - Commit and create a new Git version as below

• Check new files needed or not to be indexed, then commit files for the 6 projects to GIT and tag as a version.
• See below

How to update the JavaCC Eclipse Plugin SourceForge site

Nov 22th, 2009 / Feb 18th, 2010 / Oct 1st, 2012 / Jun 2023

Project Files

• Update the can be downloaded by users update site zip file (sf.eclipse.javacc-x.y.z-updatesite.zip) on the project file manager page through the web interface (https://sourceforge.net/projects/eclipse-javacc/files/)
  (Menu Files, move old files to eclipse-javacc sub folders, add new files, set default download for all OS for the updatesite zip file - the info icon -)

Update site

• Update the update site (https://eclipse-javacc.sourceforge.net/, to be used by the Eclipse Update Manager), through WinSCP or Putty PSFTP or Filezilla (see Project Web)

  • WinSCP:
    • create a new site: host web.sourceforge.net, port 22
  • link it to the DSA key file on the workstation
  • cd /home/pfs/project/e/ec/eclipse-javacc to go to the release directory,
    where to put the can be downloaded by users update site zip file
  • cd /home/groups/e/ec/eclipse-javacc/htdocs to go to the project web directory,
    where to put the update site release directory

  • current problems:

    • open works with SFTP, not SCP (remote shell restricted to copy operations ?);
    • cannot overwrite not owned files (even if in right group): seems to work now

  • Putty PSFTP:

    • configure putty with:
      • host web.sourceforge.net port 22 on Session
    • sf account,project (e.g. mmazas,eclipse-javacc) on Connection / Data*
    • add the private key file path on Connection / SSH / Auth
    • and save session
    • run psftp, open web.sourceforge.net, it takes sf account,project, give keyboard-interactive password (not passphrase)
      or run psftp <putty_session> (e.g. SourceForge), give pass phrase
    • use sftp commands like ftp, ls, lcd, cd, put, !dir

  • Filezilla:

    • configure site with:
      • web.sourceforge.net port 22 server SFTP
    • account,project (e.g. mmazas,eclipse-javacc)
    • ask for password (keyboard-interactive-password) (not passphrase)
    • set local folder, and remote folder to /home/project-web/eclipse-javacc/htdocs
    • open connection to the site

• The structure of the update site is the following:

  • .htaccess: to enable directory browsing
  • index.html: to give some info for lost people
  • features/*.jar, plugins/*jar, artifacts.jar & content.jar: the files used by the Eclipse Update Manager
  • <x.y.z> folders for recent and future versions, containing the same as above for their version
  • headless and old_versions for older versions

Project info

• Update the project information (Project Admin / Update MetaData): version, full description

Announcement

• Send an announcement (News / New Post)

How to update the Eclipse MarketPlace JavaCC Plug-in entry

• Login into https://marketplace.eclipse.org/content/javacc-eclipse-plug
• Use the Edit menu to edit the entry (mainly version), and save

How to update the Git repository

Configuration must be: Remotes / origin :

• Host: git.code.sf.net
• Repository path: /p/eclipse-javacc/code-git
• Protocol: ssh
• Username: the SF account
• Password: the SF account password

Note that the SF account must have set a SSH public key (in Me / Account Settings... / SSH Settings) corresponding to the private key known by Eclipse (in Windows / Preferences / General / Network connections / SSH2).

Note that the version of Egit in Eclipse Neon does not work with git at SourceForge (error "algorithm negotiation failed").