Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Linux Tools Project/ChangeLog/User Guide"
(→ChangeLog Editor) |
(→Prepare ChangeLog) |
||
| (23 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | = | + | = Overview = |
The ChangeLog plug-in for Eclipse is a basic set of extensions to enable ChangeLog functionality for projects in Eclipse. | The ChangeLog plug-in for Eclipse is a basic set of extensions to enable ChangeLog functionality for projects in Eclipse. | ||
| − | Before using the plug-in, you | + | Before using the plug-in, you should set the ChangeLog preferences. These preferences include the name and e-mail address you wish to use in a ChangeLog entry. |
| − | + | The default name and e-mail address used by the ChangeLog plug-in are your workstation username and your username@hostname information, respectively. If you set the environment variables <code>ECLIPSE_CHANGELOG_REALNAME</code> and/or <code>ECLIPSE_CHANGELOG_EMAIL</code>, the ChangeLog plug-in will use these as the default name and e-mail address instead. | |
| − | + | = ChangeLog Preferences = | |
| − | + | To configure your ChangeLog preferences, navigate to <u>Window</u> > <u>Preferences</u> and click <u>ChangeLog</u>. This will open the '''''ChangeLog''''' sub-menu. | |
| − | + | [[Image:Linuxtools-ChangeLogPrefs.png]] | |
| − | + | The screenshot above displays the preferences associated with the ChangeLog plug-in. These preferences are: | |
| − | + | ||
| − | + | ; Author Name : The name of the Author to be included in the ChangeLog entry. | |
| − | + | ||
| − | + | ; Author Email : The email address of the Author to be included in the ChangeLog entry. | |
| − | + | ||
| − | + | ; Formatter : The name of the formatter module Eclipse should use for ChangeLog entries. The form of each ChangeLog entry depends on which formatter module the ChangeLog plug-in uses. The ChangeLog plug-in provides a GNU-style formatter. There is an extension point by which other plug-ins may contribute alternate formatters. | |
| − | + | ||
| − | + | ; Editor : The name of the editor module Eclipse should use for editing the ChangeLog file. | |
| − | + | = ChangeLog Editor = | |
| − | + | The ChangeLog plug-in provides a special editor for ChangeLog files. This editor has syntax highlighting and provides a ''file-hyperlink'' feature. To use the ''file-hyperlink'' feature, hold the <code>'''Ctrl'''</code> key and click on any filename to open the corresponding file. | |
| − | + | ||
| − | + | [[Image:LinuxtoolsChangeLogEditor.png]] | |
| − | + | You can also copy all <code>''ChangeLog''</code> file changes (since the last check-in to the repository) to the clipboard. To do so, first select the <code>''ChangeLog''</code> file containing changes since the last commit and, then, use the key combination <code>'''Ctrl'''</code>+<code>'''Alt'''</code>+<code>'''v'''</code> to copy those changes to the clipboard. This is useful if you wish to use the ChangeLog entry as your comment when you perform a commit. | |
| − | + | = ChangeLog Plug-in Functions = | |
| − | + | The ChangeLog plug-in has two functions: '''Insert ChangeLog''' and '''Prepare ChangeLog'''. | |
| − | ''' | + | The first time you invoke either function for a specific project, a '''''Folder Selection''''' menu will appear. This menu will allow you to select where to save the <code>''ChangeLog''</code> file for that project. |
| − | + | [[Image:LinuxToolsChangeLogFolderSectionDialog.png]] | |
| − | + | After selecting where to save the <code>''ChangeLog''</code> file, Eclipse will open it in your workspace editor. The ChangeLog plug-in will then generate an appropriate pre-compiled entry for you to edit further. You can close the <code>''ChangeLog''</code> file after saving it; when you invoke the '''Insert ChangeLog''' or '''Prepare ChangeLog''' function again, Eclipse will use the same <code>''ChangeLog''</code> file. | |
| − | + | The following sections describe both functions in more detail. | |
| − | + | == Insert ChangeLog == | |
| − | + | This function generates a single ChangeLog entry for the currently selected file in the editor. To use this function, navigate to <u>Edit</u> > <u>ChangeLog Entry</u>. Alternatively, you can also use the key combination <code>'''Ctrl'''</code>+<code>'''Alt'''</code>+<code>'''C'''</code>. | |
| − | + | [[Image:LinuxToolsInsertChangeLogMenu.png]] | |
| − | + | Invoking the '''Insert ChangeLog''' function for another file in the same project will create a new ChangeLog entry for the file. If an entry already exists for a file, invoking the '''Insert ChangeLog''' function for that file will place the insertion point in the appropriate entry. | |
| − | + | == Prepare ChangeLog == | |
| − | <p class="copyright">© Copyright Red Hat, Inc. 2009 | + | This function generates a full ChangeLog entry based on the differences between the local changes you made to a project and its source control repository. As such, using this function requires access to the the source control repository of a project. As of today, Subversion and CVS projects are supported. |
| + | |||
| + | The ChangeLog entry generated by the '''Prepare ChangeLog''' function will include new files, removed files, and modifications. To invoke this function, first select the ChangeLog file to which changes should get written to, then navigate to <u>Project</u> > <u>Prepare ChangeLog</u>. Alternatively, you can also use the key combination <code>'''Ctrl'''</code>+<code>'''Alt'''</code>+<code>'''p'''</code>. | ||
| + | |||
| + | |||
| + | [[Image:LinuxtoolsPrepareChangeLog.png]] | ||
| + | |||
| + | == Format ChangeLog == | ||
| + | |||
| + | This function formats entries in the ChangeLog editor based on the chosen formatting strategy. The formatting strategy is specified in the <u>Window</u> > <u>Preferences</u> > <u>ChangeLog</u> > <u>Formatters</u> list. At present, only the GNU format is shipped with the ChangeLog feature but it is possible to contribute other strategies. | ||
| + | |||
| + | To invoke formatting, select a section of text and either right-click and choose <u>Format ChangeLog</u> or else use the key combination '''Esc Ctrl'''+'''f'''. Note the space after '''Esc''' which means you don't hit all three keys at once. Only the last two keys need to be hit together. After pressing '''Esc''' you should see a dialog pop-up which has the various key combinations that start in the same manner. You can use your mouse to choose the appropriate one, hit '''Enter''' when <u>Format ChangeLog</u> is selected, or continue and type in '''Ctrl'''+'''f'''. | ||
| + | |||
| + | [[Image:formatChangeLog.png]] | ||
| + | |||
| + | After selection, the file is formatted as follows: | ||
| + | |||
| + | [[Image:formatChangeLog2.png]] | ||
| + | |||
| + | <p class="copyright">© Copyright Red Hat, Inc. 2009, 2013 | ||
<br>© Copyright Phil Muldoon <pkmuldoon@picobot.org> 2006. | <br>© Copyright Phil Muldoon <pkmuldoon@picobot.org> 2006. | ||
| − | <br>This documentation is licensed under the Eclipse Public License v. 1.0. | + | <br>This documentation is licensed under the Eclipse Public License v. 1.0.</p> |
Latest revision as of 13:09, 28 May 2013
Contents
Overview
The ChangeLog plug-in for Eclipse is a basic set of extensions to enable ChangeLog functionality for projects in Eclipse.
Before using the plug-in, you should set the ChangeLog preferences. These preferences include the name and e-mail address you wish to use in a ChangeLog entry.
The default name and e-mail address used by the ChangeLog plug-in are your workstation username and your username@hostname information, respectively. If you set the environment variables ECLIPSE_CHANGELOG_REALNAME and/or ECLIPSE_CHANGELOG_EMAIL, the ChangeLog plug-in will use these as the default name and e-mail address instead.
ChangeLog Preferences
To configure your ChangeLog preferences, navigate to Window > Preferences and click ChangeLog. This will open the ChangeLog sub-menu.
The screenshot above displays the preferences associated with the ChangeLog plug-in. These preferences are:
- Author Name
- The name of the Author to be included in the ChangeLog entry.
- Author Email
- The email address of the Author to be included in the ChangeLog entry.
- Formatter
- The name of the formatter module Eclipse should use for ChangeLog entries. The form of each ChangeLog entry depends on which formatter module the ChangeLog plug-in uses. The ChangeLog plug-in provides a GNU-style formatter. There is an extension point by which other plug-ins may contribute alternate formatters.
- Editor
- The name of the editor module Eclipse should use for editing the ChangeLog file.
ChangeLog Editor
The ChangeLog plug-in provides a special editor for ChangeLog files. This editor has syntax highlighting and provides a file-hyperlink feature. To use the file-hyperlink feature, hold the Ctrl key and click on any filename to open the corresponding file.
You can also copy all ChangeLog file changes (since the last check-in to the repository) to the clipboard. To do so, first select the ChangeLog file containing changes since the last commit and, then, use the key combination Ctrl+Alt+v to copy those changes to the clipboard. This is useful if you wish to use the ChangeLog entry as your comment when you perform a commit.
ChangeLog Plug-in Functions
The ChangeLog plug-in has two functions: Insert ChangeLog and Prepare ChangeLog.
The first time you invoke either function for a specific project, a Folder Selection menu will appear. This menu will allow you to select where to save the ChangeLog file for that project.
After selecting where to save the ChangeLog file, Eclipse will open it in your workspace editor. The ChangeLog plug-in will then generate an appropriate pre-compiled entry for you to edit further. You can close the ChangeLog file after saving it; when you invoke the Insert ChangeLog or Prepare ChangeLog function again, Eclipse will use the same ChangeLog file.
The following sections describe both functions in more detail.
Insert ChangeLog
This function generates a single ChangeLog entry for the currently selected file in the editor. To use this function, navigate to Edit > ChangeLog Entry. Alternatively, you can also use the key combination Ctrl+Alt+C.
Invoking the Insert ChangeLog function for another file in the same project will create a new ChangeLog entry for the file. If an entry already exists for a file, invoking the Insert ChangeLog function for that file will place the insertion point in the appropriate entry.
Prepare ChangeLog
This function generates a full ChangeLog entry based on the differences between the local changes you made to a project and its source control repository. As such, using this function requires access to the the source control repository of a project. As of today, Subversion and CVS projects are supported.
The ChangeLog entry generated by the Prepare ChangeLog function will include new files, removed files, and modifications. To invoke this function, first select the ChangeLog file to which changes should get written to, then navigate to Project > Prepare ChangeLog. Alternatively, you can also use the key combination Ctrl+Alt+p.
Format ChangeLog
This function formats entries in the ChangeLog editor based on the chosen formatting strategy. The formatting strategy is specified in the Window > Preferences > ChangeLog > Formatters list. At present, only the GNU format is shipped with the ChangeLog feature but it is possible to contribute other strategies.
To invoke formatting, select a section of text and either right-click and choose Format ChangeLog or else use the key combination Esc Ctrl+f. Note the space after Esc which means you don't hit all three keys at once. Only the last two keys need to be hit together. After pressing Esc you should see a dialog pop-up which has the various key combinations that start in the same manner. You can use your mouse to choose the appropriate one, hit Enter when Format ChangeLog is selected, or continue and type in Ctrl+f.
After selection, the file is formatted as follows:
© Copyright Red Hat, Inc. 2009, 2013
© Copyright Phil Muldoon <pkmuldoon@picobot.org> 2006.
This documentation is licensed under the Eclipse Public License v. 1.0.