Skip to content

Modify an App in the Repository

Jump to bottom
dpefour edited this page Apr 15, 2014 · 15 revisions

Note: It is recommended to read first Adding a new app to the repository as a prerequisite of this document.

How to Modify an existing app

The process for modifying an app is fairly similar to that of adding a new app. The difference is that you are typically making smaller check-ins to fewer files. Usually modifying a single file to fix a bug or adding a new proc.

The approval process is also equivalent as adding a new app. The pull request is sent to the Gate Keepers and the app owner (you if you are the app owner or someone else if you are just contributing to another app) will need to verify that the new code does not break the regression suite and passes the linter.

  1. Clone the GitHub repo to a local repository <WORKING_DIR>

On Windows

cd <WORKING_DIR>
git clone https://github.com/<USER>/XilinxTclStore.git
cd XilinxTclStore
git checkout master
git remote add upstream https://<USER>@github.com/Xilinx/XilinxTclStore.git

On Linux

cd <WORKING_DIR>
git clone https://<USER>@github.com/<USER>/XilinxTclStore.git
cd XilinxTclStore
git checkout master
git remote add upstream https://<USER>@github.com/Xilinx/XilinxTclStore.git
  1. Update the content of the local repository with the latest content from Xilinx Tcl Store

The local repository must first be updated with the content from the upstream remote (Xilinx Tcl Store). This can be done with a single git pull command or a combination of git fetch and git merge commands. Once the local repository has been updated, it can be pushed to the origin remote before making any change:

git pull upstream master
git push origin master

  1. Add/modify the appropriate file(s)

  2. Disable Catalog Refresh

It is recommending to disable the catalog refresh during the development stage. To disable refresh capability, the following Tcl param can be set in the startup init.tcl script for all Vivado sessions:

set_param tclapp.enableGitAccess 0

  1. Change the Tcl repository location from within Vivado

The location of the Tcl app repository can also be specified from within Vivado with the following parameter:

set_param tclapp.sharedRepoPath <WORKING_DIR>/XilinxTclStore

  1. Source all the new and/or updated Tcl scripts to make sure they don't have any syntax error

  2. Run the linter and fix any errors

  3. Run the package generation flows and make sure the pkg and tcl index files are added

  4. This step is only for the app owner:

Update the app version number. If the version is not updated, the changes made in the app won't be pulled by other users. Updating the app version also require to re-generate the pkgIndex.tcl with the pkg_mkIndex command.

The app version is the same as the Tcl package version of the app. For example, the following line defines the app version 1.4 (i.e Tcl package version 1.4) for the designutils app:

package provide ::tclapp::xilinx::designutils 1.4

Each app must have a single file where the package version is provided.

Note: The package version number should have the format <MAJOR_VERSION>.<MINOR_VERSION>. The <MINOR_VERSION> version number needs to be incremented for every change made to the app. Otherwise Vivado will not be able to pull the changes from GitHub. The <MAJOR_VERSION> version number needs to be incremented only when the changes in the app's API are such that it is no more compatible with the previous version. Those requirements are directly driven by the Tcl language and how it handles packages.

  1. If a new script is added to the app, then add a new test script to the app's regression test suite.

if the only changes are updates in some existing script(s), then verify whether the changes should result in adding one of more test to the app's regression test suite

  1. Run the regression test suite of the app and verify that none of the tests have been broken
source <WORKING_DIR>/XilinxTclStore/tclapp/<company>/<app>/test/test.tcl
  1. Digitally sign the mandatory copyright/legal document

The contributor's code can only be merged inside the Xilinx Tcl Store is he/her as digitally sign the copyright/legal document under the following location:

<WORKING_DIR>/XilinxTclStore/tclapp/<company>/<app>/doc/legal.txt

Refer to the Open Source BSD 2 license (BSD 2-Clause License ) for further information.

There must be an entry, <YYYYMMDD Date>::<github id>::<Full Name>, per contributor of the app. If all the contributors are from the same company, it is allowed to have a single digital signature for the app owner.

The format <YYYYMMDD Date>::<github id>::<Full Name> is, for example:

20140221::dpefour::David Pefourque

Note: the <github id> is the GitHub User ID, not the company email or Linux identifier.

  1. Commit your changes to your GitHub repo
git add <files_to_include_in_the_commit>
git commit -m '<commit message>'
git push origin master
  1. Go to github.com and issue a pull request
Clone this wiki locally