|
| 1 | +# Contributing to Eclipse Trace Compass Incubator |
| 2 | + |
| 3 | +Thanks for your interest in this project. This page explains how to contribute code to the Trace Compass Incbator project. |
| 4 | + |
| 5 | +The Trace Compass Incubator is a project that contains additional features: |
| 6 | + |
| 7 | +- That are under development, but still usable enough to be used and tested by users. |
| 8 | +- Whose content relates to a specific trace type or domain of analysis (for example virtual machine analyses) and that no other plugin will depend on. |
| 9 | + |
| 10 | +This project is a permanent incubator, i.e. the features will never be officially released with a specific version, hence, nothing will be API in the plugins developed there. Some feature may eventually graduate to the Trace Compass project itself if required, for example if many other features depend on them or they provide an interesting functionality for the core Trace Compass. |
| 11 | + |
| 12 | +## Terms of Use |
| 13 | + |
| 14 | +This repository is subject to the [Terms of Use of the Eclipse Foundation][terms]. |
| 15 | + |
| 16 | +## Code of Conduct |
| 17 | + |
| 18 | +This project is governed by the [Eclipse Community Code of Conduct][code-of-conduct]. |
| 19 | +By participating, you are expected to uphold this code. |
| 20 | + |
| 21 | +## Eclipse Development Process |
| 22 | + |
| 23 | +This Eclipse Foundation open project is governed by the [Eclipse Foundation Development Process][dev-process] and operates under the terms of the [Eclipse IP Policy][ip-policy]. |
| 24 | + |
| 25 | +## Eclipse Contributor Agreement |
| 26 | + |
| 27 | +In order to be able to contribute to Eclipse Foundation projects you must electronically sign the [Eclipse Contributor Agreement (ECA)][eca]. |
| 28 | + |
| 29 | +The ECA provides the Eclipse Foundation with a permanent record that you agree that each of your contributions will comply with the commitments documented in the Developer Certificate of Origin (DCO). Having an ECA on file associated with the email address matching the "Author" field of your contribution's Git commits fulfills the DCO's requirement that you sign-off on your contributions. |
| 30 | + |
| 31 | +For more information, please see the [Eclipse Committer Handbook][commiter-handbook]. |
| 32 | + |
| 33 | +## Source code tree |
| 34 | + |
| 35 | +This source tree contains the source code for the Trace Compass incubator plugins for Eclipse. |
| 36 | + |
| 37 | +The plug-ins are categorized as follows: |
| 38 | + |
| 39 | +```text |
| 40 | + analysis/ | Analysis extensions to the base framework |
| 41 | + common/ | Basic release engeneering (e.g. target definitions, update site) |
| 42 | + doc/ | Documentation and code examples |
| 43 | + rcp/ | Code specific to the RCP version |
| 44 | + scripting | Plug-ins providing scripting capabilities, e.g. javascript, Python using EASE |
| 45 | + skeleton/ | Skeleton plug-ins for adding new plug-ins/features to the repository |
| 46 | + trace-server/ | Trace Compass server plug-ins and RCP |
| 47 | + tracetypes/ | Plug-ins providing new trace types (e.g. ftrace, ROS2) |
| 48 | + vm/ | LTTng virtual machine analysis |
| 49 | +``` |
| 50 | + |
| 51 | +## Getting started |
| 52 | + |
| 53 | +So, you have a new feature to propose. First follow instruction in the [Trace Compass Development Environment Setup][tc-dev-setup] guide of the `Trace Compass parent project`. |
| 54 | + |
| 55 | +Note: Use the target file `tracecompass-incubator-master.target` under directory `common/org.eclipse.tracecompass.incubator.target` instead of the parent project's target file. |
| 56 | + |
| 57 | +The sources section contains the git repository for the incubator. Make sure to clone it and add the plugins to the workspace. |
| 58 | + |
| 59 | +In the source tree, there is a helper script that will create the necessary plugins for a new feature, including feature, ui, unit tests and documentation plugins. |
| 60 | + |
| 61 | +```bash |
| 62 | +cd org.eclipse.tracecompass.incubator |
| 63 | +./skeleton/create_new_feature.py -h # This will display the help message for the script with the available arguments |
| 64 | +./skeleton/create_new_feature.py --dir tracetypes --copyright "École Polytechnique de Montréal" "My Awesome Tracetype" |
| 65 | +``` |
| 66 | + |
| 67 | +This last command will create 6 plugins in directory ''tracetypes'' named ''org.eclipse.tracecompass.incubator.my.awesome.tracetype'' with the Activators initialized, the pom.xml files already populated, etc. You are now ready to import those plugins in Eclipse and start developing. |
| 68 | + |
| 69 | +## Contributing a feature/patch |
| 70 | + |
| 71 | +Read the [documentation on how to contribute](tc-contrib) of the Eclipse Trace Compass parent project to prepare to push your contribution as pull request. |
| 72 | + |
| 73 | +This will send the patch to GitHub pull request, where it will be timely reviewed by a member of the community. |
| 74 | + |
| 75 | +### Review guidelines |
| 76 | + |
| 77 | +For new features, the review of two committers is necessary. The patch will not be reviewed in details. Some comments may be done on the code style, but they are not in themselves reasons for rejection of a patch. What will be verified: |
| 78 | + |
| 79 | +- Does the feature work and integrate well with Trace Compass |
| 80 | +- Does it seem stable enough (no obvious race conditions or UI freeze when simply playing around) |
| 81 | +- Is there a minimal documentation to help the reviewer test and evaluate the feature. If adding a new trace type or analysis without providing a link to a trace to test it on, it will be hard to review. |
| 82 | +- Are there some unit tests. Though not mandatory for a first pass on the feature, it is highly advised to have some basic unit tests, to help the maintainability |
| 83 | + |
| 84 | +### Incubator committers |
| 85 | + |
| 86 | +Since the incubator is meant to receive a lot of patches for different domains/trace types, not all committers are expected to know/maintain the full code base. Someone contributing a new feature will thus gain committers status quite rapidly once the feature is merged and is expected to be the official maintainer of that part of the code, hence should do the reviews on those plugins or at least make sure that the code does not go unmaintained and patches slip in the cracks. |
| 87 | + |
| 88 | +## Publishing a feature |
| 89 | + |
| 90 | +The script mentioned in the first section will create the plugins, but it will not publish it on the incubator update site. Some additional steps are required. |
| 91 | + |
| 92 | +### Prepare the feature |
| 93 | + |
| 94 | +First the feature plugins needs to be made ready with the proper dependencies, especially if some of those are themselves part of the incubator. The feature plugin is the one with no suffix. In the example above it would be ''org.eclipse.tracecompass.incubator.my.awesome.tracetype''. |
| 95 | + |
| 96 | +- Open the ''feature.xml'' file in that plugin to open the feature editor. |
| 97 | + - In the ''Included plugins'' tab, make sure all the plugins that will be part of the feature are there. They are usually the .core, .ui and .doc.user plugins, the unit tests are not included. |
| 98 | + - In the ''Dependencies'' tab, click on the ''Compute'' button next to the list box on the left. This will list all the plugins that are necessary for the plugins of this feature to work. |
| 99 | +- Open the ''feature.properties'' file |
| 100 | + - Edit the properties as you want to see them in the update site |
| 101 | + |
| 102 | +### Add it to the update site |
| 103 | + |
| 104 | +The project containing the update site content is ''org.eclipse.tracecompass.incubator.releng-site''. |
| 105 | + |
| 106 | +- Open the ''category.xml'' file |
| 107 | + - You can now add your feature under the corresponding category or create a new category if necessary. |
| 108 | + |
| 109 | +## UX concerns |
| 110 | + |
| 111 | +Some minor things to remember when making new UIs is to remember that a human needs to operate them. Here are some minor guidelines to help out: |
| 112 | + |
| 113 | +- The amount of time needed to click an item is directly proportional to the distance of the item and inversely proportional to the size of the item. So, making a user hunt for an item like "Where's Waldo(tm)" will typically decrease engagement. (Fitt's law) |
| 114 | +- The amount of notions a user can juggle at once is typically seven, plus or minus two. This means a view should not have more than 5 metrics shown at once. (Miller's law) |
| 115 | +- People will "fill in the blanks" so we half create what we perceive. This (Behavioural economics) |
| 116 | +- Have fun and be creative, we want to incubate great new ideas. |
| 117 | + |
| 118 | +## Note for maintainers |
| 119 | + |
| 120 | +To make sure that the current incubator is working with a Trace Compass mainline release read the infomration [here][maintainer-info]. |
| 121 | + |
| 122 | +## Building the application |
| 123 | + |
| 124 | +In order to build the application from command-line, Maven is used. For more information about building the application see the description in the [BUILDING](BUILDING.md) file. |
| 125 | + |
| 126 | +## When to submit patches |
| 127 | + |
| 128 | +Remember that contributions are always welcome! |
| 129 | + |
| 130 | +If you have a simple and straightforward fix to an obvious bug, feel free to push it directly to the project's GitHub (see below). |
| 131 | + |
| 132 | +This project uses GitHub issues to track ongoing development and issues. In order to contribute, please first [open an issue][issues] that clearly describes the bug you intend to fix or the feature you would like to add. Make sure you provide a way to reproduce the bug or test the proposed feature. |
| 133 | + |
| 134 | +If you wish to work on a larger problem or feature, it would be a good idea to [contact us](#contact) first. It could avoid duplicate work in case somebody is already working on the same thing. For substantial new features, it is always good to discuss their design and integration first. |
| 135 | + |
| 136 | +Be sure to search for existing bugs before you create another one. |
| 137 | + |
| 138 | +Note that before migrating to GitHub issues ongoing development and issues were tracked using Bugzilla. The bugs were not batch migrated. Only selected issues have been migrated to GitHub issues. You can search for [here][bugzilla] for Bugzilla issues. |
| 139 | + |
| 140 | +## Where to submit |
| 141 | + |
| 142 | +The Trace Compass project uses GitHub pull requests for submitting patches and review contributions |
| 143 | + |
| 144 | +Once you have your code ready for review, please [open a pull request][pull-requests]. Please follow the [pull request guidelines][pr-guide]. |
| 145 | + |
| 146 | +## Pull request guidelines |
| 147 | + |
| 148 | +**Changes to the project** are made by submitting code with a pull request (PR). |
| 149 | + |
| 150 | +- [How to write and submit changes][creating-changes] |
| 151 | + |
| 152 | +**Good commit messages** make it easier to review code and understand why the changes were made. |
| 153 | +Please include a: |
| 154 | + |
| 155 | +- `Title:` Concise and complete title written in imperative (e.g. "Update Gitpod demo screenshots" |
| 156 | +or "Single-click to select or open trace") |
| 157 | +- `Problem:` What is the situation that needs to be resolved? Why does the problem need fixing? |
| 158 | +Link to related issues (e.g. "Fixes #317"). |
| 159 | +- `Solution:` What changes were made to resolve the situation? Why are these changes the right fix? |
| 160 | +- `Impact:` What impact do these changes have? (e.g. Numbers to show a performance improvement, |
| 161 | +screenshots or a video for a UI change) |
| 162 | +- [*Sign-off:*][sign-off] Use your full name and a long-term email address. This certifies that you have written the code and that, from a licensing perspective, the code is appropriate for use in open-source. |
| 163 | + |
| 164 | +## Contact |
| 165 | + |
| 166 | +Contact the project developers via the [project's "dev" mailing list][mailing-list] or open an [issue tracker][issues]. |
| 167 | + |
| 168 | +[bugzilla]: https://bugs.eclipse.org/bugs/buglist.cgi?product=Tracecompass.incubator |
| 169 | +[issues]: https://github.com/eclipse-tracecompass/org.eclipse.tracecompass.incubator/issues |
| 170 | +[code-of-conduct]: https://github.com/eclipse-tracecompass/org.eclipse.tracecompass.incubator/blob/master/CODE_OF_CONDUCT.md |
| 171 | +[commiter-handbook]: https://www.eclipse.org/projects/handbook/#resources-commit |
| 172 | +[creating-changes]: https://www.dataschool.io/how-to-contribute-on-github/ |
| 173 | +[dev-process]: https://eclipse.org/projects/dev_process |
| 174 | +[eca]: http://www.eclipse.org/legal/ECA.php |
| 175 | +[ip-policy]: https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf |
| 176 | +[mailing-list]: https://dev.eclipse.org/mailman/listinfo/tracecompass-dev |
| 177 | +[maintainer-info]: https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/wiki/Align_to_tc_releases |
| 178 | +[pr-guide]: #pull-request-guidelines |
| 179 | +[pull-requests]: https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/pulls |
| 180 | +[sign-off]: https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff |
| 181 | +[tc-dev-setup]: https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/blob/master/DEVELOPMENT_ENV_SETUP.md |
| 182 | +[terms]: https://www.eclipse.org/legal/termsofuse.php |
0 commit comments