Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
OSEE/Developer Setup
< OSEE
Contents
Initial Setup
- Create a Tools Folder on your C: Drive - C:\Tools
- Copy the Engineering Notebook and save to your C:\Tools. Open and read contents then clear examples to start using.
- Install Programs
- Create an Eclipse account using your email address
- Sign Eclipse Contributor Agreement by going to View Profile then under Status select Eclipse Contributor Agreement
- Code Reviews - the following links provide access to review code, add links to your browser favorites
- Read Gerrit Tutorial
- Bookmark and log into: Gerrit at Eclipse.org using eclipse.org un/pw.
- When reviewing code, use the Developer Peer Review Checklist
- Email (Donald Dunne) donald.g.dunne AT boeing.com to add you as an OSEE Admin
- Log into Bugzilla using Eclipse username/password
- Sign-up to osee-developers mailing list
- Add logback-dev.zip to C:/Tools/
- Go to File:Logback-dev.zip and save the file
- Open the .zip file and copy the logback-dev.xml file
- Paste the .xml file into C:/Tools/
Git Setup
- Install Git using the following installation settings
- Adjusting your PATH environment
- Use git from the windows command prompt
- Choosing HTTPS transport backend
- Use the OpenSSL library
- Configuring the line ending conversions
- Check as-is, commit as-is
- Configuring the terminal emulator to use with Git Bash
- Use MinTTY
- Leave the rest of the settings as default
- Adjusting your PATH environment
- Create a folder in Tools called git_main so the path is C:/Tools/git_main
- Open the following link and download the zip file File:Gitconfig global.zip
- Open the zip file and copy the gitconfig_global file into the Tools Folder
- Execute the following command, replacing <user> with your user directory
- cp C:/Tools/gitconfig_global C:/Users/<user>/.gitconfig
- Edit the .gitconfig and replace your name and email (Edit in text editor such as Notepad++)
- Open Git Bash from the Start Menu
- Execute the following commands
- cd C:/Tools/git_main
- git clone https://<your_gerrit_username>@git.eclipse.org/r/osee/org.eclipse.osee.git
- cd org.eclipse.osee
- git checkout dev
- Setup Local_hooks by downloading File:Local hooks.zip
- Open the zip file and copy the local_hooks folder to C:/Tools
- Execute the following command
- cp C:/Tools/local_hooks/* C:/Tools/git_main/org.eclipse.osee/.git/hooks/
- You can now delete the folder C:/Tools/local_hooks
- Add your name to usersList.txt in C:/Tools/git_main/org.eclipse.osee/.git/hooks/usersList.txt
OSEE Workspace Setup
OSEE Setup
- Install OSEE/Eclipse (TBD - replace with how to create OSEE dev workbench that compiles)
- Latest Dev Alpha Kit may be found at https://ci.eclipse.org/osee/job/osee_nightly/lastSuccessfulBuild/artifact/org.eclipse.osee/plugins/org.eclipse.osee.client.all.product/target/products/
- Unzip it to an empty target folder
- If your PC environment's security software prevents running executable code from your user profile, add this line to the osee.ini file in the target folder you just unzipped into:
- -Duser.home=C:\Tools\userhome
Importing Git Projects
- Start an OSEE version that matches the code you want to develop (e.g. dev alpha to develop in dev)
- Create a workspace
- In OSEE, follow the menu Project->Build Automatically, and uncheck this option
- Open the Git Perspective by following the menu Window->Perspective->Open Perspective
- Click the first "GIT" icon labeled, Add an existing local Git Repository
- Browse to select the git directory (created in a previous section above, e.g. C:\Tools\git_main), then click Search
- In the Search and select Git repositories on your local file system dialog, choose org.eclipse.osee
- Click the Add button
- Right-Click on the org.eclipse.osee repository now showing in the Git Repositories view and select Import Projects...
- In the dialog that pops up if the first project is "org.eclipse.osee", uncheck that box
- Make sure all other projects are checked
- Click Finish
Configure Workspace
- Double check to make sure the OSEE environment you are pulling code into matches the code you have.
- e.g. if you are developing for the dev line, make sure your osee is a dev version.
- Import OSEE Team Preferences
- Switch back to the Java Perspective, then File->Import, in the import wizard, select General->Preferences and click Next
- In the From preference file: input box, enter the path to the preferences (substitute your directory for <git dir>) in the From preference file:
- Browse to <git dir>\org.eclipse.osee\plugins\org.eclipse.osee.support.config then select the preference file: osee_team_preferences.epf and click Open.
- Leave "Import All" checked and Choose Finish. Accept the prompt to restart the IDE.
- Set Target Platform
- Select Window -> Preferences
- Expand Plug-in Development -> Target Platform
- Check OSEE Client Server Target Platform
- Click Apply then Apply and Close
- Turn Project->Build Automatically back on
- Remove errors that we do not care about
- In the Problems tab at the bottom of OSEE, select the white triangle icon on the right side
- Choose Filters...
- Uncheck Show all items
- Choose New under Configurations
- Deselect "Errors / Warnings on Project", then make sure New Configuration is both selected and highlighted
- Under Types, click Deselect All for the errors
- Go through the list of types selecting all Java, Javascript, and Plug-in Problems
- Click Apply and Close
- Remove Null Analysis Errors
- Choose Window->Preferences->Java->Compiler->Errors/Warnings
- Expand Null Analysis and set the following to Warning instead of Error
- Null pointer access
- Potential null pointer access
- Redundant null check
- Uncheck Enable annotation-based null analysis
- Click Apply (which will prompt to rebuild all) then Apply and Close
- After the rebuild there should no longer be any errors, otherwise ask your Mentor
Other OSEE Settings
- Package Explorer > White Pull down Arrow > Package Presentation > Change to Hierarchical from Flat (if preferred)
OSEE Setup Checks
- Run Test Suites / DB Init
- Under Run->Debug Configurations, OSGi Framework, select "OSEE_Application_Server[HSQLDB]" and click Debug to run it
- In the Console output scroll from the application server, look for these two lines to verify correct startup:
- Registered servlet '/osee/client/loopback'
- Registered servlet '/osee/console'
- Once server is loaded, go to Run->Debug Configurations, JUnit Plug-in Test, select "AtsIde_Integration_TestSuite" and click Debug to run it
- You can generally safely click on "Continue" if you get a validation pop-up (eg. "rest.assured"). These typically come from incompletely cleaned-up removed dependencies.
- Once ~100 tests have loaded and passed in JUnit, stop the tests, terminate and relaunch the Application Server
- Run "OSEE_IDE_[localhost]" under Eclipse Application in Debug Configurations
- OSEE IDE should load without issue
Other Programs & System Configuration
- Wiki for Documentation
- Bookmark and log into Eclipse.org Wiki
- Log in and bookmark Jenkins Build Page
Reading & Training Material
- Read important Eclipse training at Eclipse Help
- Read "Workbench User Guide" sections
- Getting Started
- Tips and Tricks
- Read "Java development user guide" sections:
- Getting Started
- Read "Platform Plug-in Developers Guide" sections:
- Welcome to Eclipse
- Simple plug-in example
- Runtime overview
- Read "Plug-in Development Environment Guide" sections:
- PDE Overview
- Concepts
- Read "Workbench User Guide" sections
- Watch videos on How Do I Author CM Managed Changes
- Read Agile Tutorial
- Read REST Tutorial
- Read OSEE Software Development Process
- Read OSEE Developer Guidelines
- Read OSEE Acronyms
- Read OSEE Architecture
- Bookmark and browse User Training
- Watch short User Training videos
- Bookmark and watch all (TBD) Developer Videos
Git Information & Support
When making your first push to Gerrit OSEE you will need to sign-in
- After making submitting the push in Git Bash, a Windows log-in screen will pop up
- Go to the OSEE Gerrit Page, and then your account settings
- Open 'HTTP Password, click 'Generate Password'
- Use this username and password as the log-in that was prompted by git bash
The OSEE Git repository contains the following main branches:
- master: origin/master is the main branch where HEAD always reflects a production ready state.
- dev: origin/dev is the main branch where HEAD always reflects a state with the latest delivered development changes for integration.
- 0.XX.X: origin/0.XX.X is the main branch where HEAD always reflects a state with the latest changes from development that have been tested/built and ready for customer assurance testing. This branch reflects the last development changes that have been incorporated into a release candidate.
- Developers wanting to incorporate a change for a specific build should make the change in that build's development branch (ex. dev).
- ☞ Developers should not make changes on master branches
Additional Git Commands Collection of Useful Git Commands
Name | Description | Commands |
---|---|---|
Stash | Stores changes into a stack |
git stash save <message> git stash list git stash show -p stash@{0} git stash drop stash@{0} git stash pop |
Selective Push | Push only commits from a certain point (HASH) and prior |
git push origin HASH:remoate_branch_name |
Show Modified File Names | Lists files modified |
git show --name-only HASH path |
Show changes introduced by each commit | shows commit change information |
git whatchanged --name-only git whatchanged -2 --name-only #to display the last two git whatchanged --format=email --name-only #display in email format |
Undo | Undo local changes |
git rebase -i HEAD~5 git reset --hard HEAD git reset --hard HEAD~3 git reset --hard <specific_commit_id> |
Show Commit File Differences | Compares files from current commit with previous commit |
git diff HASH |
Compare two commits | Compares files between two commits |
git diff OLDHASH NEWHASH |
Compare two branches | Compares changes made between two branches |
git diff branch1..branch2 git diff localBranchName..origin/remoteName |
Find common ancestor | finds best common ancestor(s) between two commits |
git merge-base branch1..branch2 |
Git Log | view history for a given path even if it has been moved/renamed |
git log --follow [current path] |
Git Log | vew current branch activity |
git log --name-only HASH git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative |
Git Log | Print single log entry |
git log -1 branch_name |
Git Log | Show full history even with removed commits |
git reflog show [log-options] master |
Create a local branch | Creates a branch and switches working tree to new branch |
git checkout -b newLocalBranchName sourceBranch |
Create a local tracking branch | Creates a local tracking branch called your_branch_name_here and switches working tree |
git checkout -b your_branch_name_here origin/0.9.7_dev |
Switch branches | switches the working tree to a different branch |
git checkout [master|94|...] |
Sharing a local work branch with others | Switch to working branch, Push working branch to remote |
git checkout <working_branch_name> git push origin <working_branch_name>:refs/heads/<working_branch_name> |
Merge onto current branch | Merge branch into current branch, if there is nothing to merge a fast-forward will be performed. HEAD pointer moved to HEAD of branch |
git merge branch |
Branching and Merging | To replace with incoming file so you can re-make your changes (or abandon them) |
git checkout --[theirs|our] <path> |
Merging Again | What to do if you are in the middle of a rebase and don't want the previous merge resolution |
git checkout --conflict=merge -- <file you want to remerge> |
Continue rebasing | After conflicts have been resolved |
git rebase --continue |
Patches | Generating individual patches (one per commit) to submit by email (or bug report), exports all commits made to current branch, from trunk to HEAD "-o ../" puts them one level above in individual .patch files |
git format-patch -o ../ trunk..HEAD |
Patches | Create a patch with the top n number of commits |
git format-patch -n |
Local Change Patch | Generate a big patch for your local changes, (good for backup), In this case Z:\ is mounted as a shared windows folder, so if you do not have faith in your local backup software, this could help you quickly restore your work. |
git diff trunk HEAD -p > Z:/backup_date_time.patch |
Splitting commits | In case you have multiple, conceptually unrelated changes in a single commit you can split them by doing an interactive rebase |
--Rebase current working tree git rebase -i HASH_WHERE_TO_START_FROM -- mark 'e' or 'edit' the commit you want to Edit/Split. -- When you get dropped back into the shell, issue: git reset HEAD^ --which effectively undoes that -- commit and leaves the modified files unstaged ProGit Book Chapter 6-4 -- Afterwards you can 'add' and 'commit' changes as appr. --To resume rebase operation issue: git rebase --continue |
Change author name/email of a commit with yours | Edit commit author, email, or comments using the following. This should only be performed on commits that have not been pushed to the remote repository. If you just need to change the author name you can change --reset-author with --author AUTHOR NAME |
git rebase -i SHA_OF_COMMIT_PREVIOUS_TO_TARGET git commit --amend --reset-author -- Repeat this and the next step for each file git rebase --continue |
Clean up untracked files from repository | Remove untracked files and directories from the working tree |
git clean -fdx |
Tagging a Build | Create, and Push a Tag |
git tag -a -m "0.9.6.v201009271203 Release Candidate" 0.9.6.v201009271203_RC <COMMIT_ID TO TAG> git push origin 0.9.6.v201009271203_RC |
Deleting a Tag | Delete a Tag locally and push change to remote |
git tag -d 0.9.6.v201009271203_RC git push origin :refs/tags/0.9.6.v201009271203_RC |
delete remote branch | different than just deleting a local branch |
git push origin --delete branchName |
List all Tags | List tags |
git tag -l |
Create empty branch | Create an empty branch for disjoint histories |
git symbolic-ref HEAD refs/heads/newbranch rm .git/index git clean -fdx <do work> git add your files git commit -m 'Initial commit' |
Create Mapped Drive Git Repo | Use mapped drive to host remote Repo for personal use |
Note: in this example i is mapped to a remote disk share git init --bare --shared=0600 /i/git/user.git cd /c/Tools/git git clone /i/git/user.git/ cd user copy your files in git add -A git commit -m "initial commit" git push origin master |
Create Git Repo using SSH | Use SSH to host remote Repo for personal use |
on the remote host: git init --bare --shared=0600 /<path>/user.git chmod 700 /<path>/user.git on local machine: cd /c/Tools/git git clone ssh://<user_name>@<host>/<path>/user.git cd user copy your files in git add -A git commit -m "initial commit" git push origin master |
Remove stale remote branches | Use Prune to remove stale remote branches (add --dry-run to preview what will be changed) |
git remote prune origin |
Find dangling Commits | Find dangling commits |
git fsck --full --no-reflogs | grep commit -- or to show the names of each run: for i in `git fsck --full --no-reflogs | grep commit | awk '{print $3}'`; do git show $i --name-only; done |
Fast Export/Fast Import | Use to move a project from one repo to another repo preserving history |
git fast-export branchToExport pathOfSourceProject(s) | (cd destinationRepo && git fast-import) -- done from source repo |
Remove all instances of a file from history | Run through all commits in history and remove the named file/s. Also delete commits that would be empty once the file is deleted. Useful for things like large binary files that are taking up too much space and shouldn't have been committed. |
git filter-branch --index-filter 'git ls-tree --name-only --full-tree $GIT_COMMIT | grep "folder/my.file" | xargs git rm --cached -r --ignore-unmatch test.txt ' --prune-empty -f -- --all |
Git Resources
- Git Commands
- Git Workflows
- Git Conflicts/Merging