Skip to content

Modify an App in the Repository

Jump to bottom
dpefour edited this page Jun 26, 2015 · 15 revisions

Important information about Git branch in this document

Although most of the contributions typically target the master branch, the actual branch accepting contributions depends on the Vivado release and needs to be checked on this page.

In this document, the Git branch can be refered as master or <branch> but the exact Git branch name should be used for all the Git commands of this document.

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 <branch>
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 <branch>
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 <branch>
git push origin <branch>
  1. Add/modify the appropriate file(s)

Note: all the scripts within the same app should require the same Vivado package version. Refer to the version requirement for additional information.

  1. Change the Tcl repository location for Vivado

The location of the Tcl app repository is specified with the environment variable XILINX_TCLAPP_REPO:

export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore
export XILINX_LOCAL_USER_DATA=NO

Note: The environment variable XILINX_LOCAL_USER_DATA needs to be set to NO to disable caching of the catalog XML files

  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. Re-generate the app XML file

Refer to Update the App XML File in this page

  1. Re-generate the release XML files for GUI testing

Refer to Update the Release XML File for GUI testing in this page

Note: the release XML files should never be committed with the app changes. Those files should only be generated for GUI testing

  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 <branch>
  1. Go to github.com and issue a pull request for the branch <branch>
Clone this wiki locally