= GIt repository naming conventions = Please follow these conventions when creating a repository containing code |Type |Name |Short Name| |------|-------|-------------| | ActionBars | {name} ActionBar | ijab-... | | Plugins | {name} Plugin | ijp-... | | Macros | {name} Macro | ijm-... | | Scripts | {name } Script | ijs-... | | XTensions | {name} XT | xt-... | | Python Projects | {name} Python | py-...| Use dash (`-`) as separators, and non capital letters. For instance `ijp-bigdataviewer-segment`. = BIOP repositories using CI and available in scijava-maven = - https://github.com/BIOP/ijl-utilities-wrappers - https://github.com/BIOP/pyimagej-scijava-command - https://github.com/bigdataviewer/bigdataviewer-playground - https://github.com/BIOP/bigdataviewer-bioformats - https://github.com/BIOP/bigdataviewer-playground-display - https://github.com/BIOP/ijp-imagetoatlas - https://github.com/BIOP/bigdataviewer-biop-tools - https://github.com/BIOP/ijp-kheops - https://github.com/BIOP/bigdataviewer-spimdata-extras - https://github.com/BIOP/bigdataviewer-selector - https://github.com/BIOP/ijp-operetta-importer - https://github.com/BIOP/EasyXT-FIJI - LaRome TODO = Git Remote Management = There are two remote git management systems: [c4science](https://c4science.ch/) and [github](https://github.com/). c4science can be used during non-public development. However private repositories can also be created on github, and with an academic account, even on personal github accounts. The need for the c4science git management system is unclear at the moment, but its documentation is still accessible at the end of this page. = GitHub BIOP Account = Oli created [an account for the BIOP on GitHub](https://github.com/BIOP). That way our public work is more visible and more professional. All BIOP members are administrators and can add more people and create repositories. = Scijava Maven, Github actions and reproducible repository releases = The procedure described below will help you to: * make a reproducible piece of code * allow others to use your code easily The procedure described below is aimed at making java repositories in the scijava ecosystem. Other things exist for python, c, etc. But since what we do at the BIOP is currently java packages for Fiji and QuPath, the procedure described below is worth knowing and following. Briefly, you will have to abide by certain rules when creating a repository. These rules will allow github, via github actions, to build your repo for each commit, potentially test it (if you put tests), and also make release available through the web server maven.scijava.org. NOTE: What this does do, is handling Fiji update sites - manual uploads are still required. See Curtis forum post: https://forum.image.sc/t/scijava-ci-migration-from-travis-ci-to-github-actions/57573 The BIOP organization has 'secrets' shared with scijava maven, and thus all repos created and present in the BIOP organization can use CI. This is not the case if your repository is on your personal github account. So to enable CI on a personal, you have to give ownership to BIOP before (otherwise you need to contact a scijava administrator). To change the ownership of a github repository, go to {nav Settings} and choose {nav Transfer ownership} from the {nav Danger Zone}. Enter "BIOP". On your local computer, update your repository's remote url : ``` $ git remote set-url origin <biop_remote_url> ``` The procedure for CI is explained below. Some parts have to be setup once, some parts one time for each repository (enabling CI for a repo), and some actions have to be performed each time you want to trigger a release, once CI has been enabled. == To do once: clone the `scijava-scripts` once at the proper file hierarchy location == The repository https://github.com/scijava/scijava-scripts contains all the useful scripts used for continuous integration. These scripts will have to be executed in order to enable CI for a repository or to make a new release. This repository needs to be present locally in your computer. * clone https://github.com/scijava/scijava-scripts and - it will ease the execution of these scripts - put the scripts repo at the same hierarchy as all the other repos you want to enable CI: {F16193593} == To do once: install xmllint for Windows == Follow the answered procedure described in: https://stackoverflow.com/questions/19546854/installing-xmllint **OR** Copy the `xmllint` folder located at `\\svfas6.epfl.ch\biop\biop\Informatics\Software Library\XMLLINT` at the C:\ and add the `bin` folder to the `PATH` system environment variable, eg `Path : C:\xmllint\bin` == To do for each repository once, in order to enable CI == == To do once: add some software to the System environment variable == Add: * Java jdk (check `C:\Program Files\Jetbrains\IntelliJ\Java\Jdk\`) * Maven: (check `C:\Program Files\JetBrains\IntelliJ IDEA Community Edition 2021.1\plugins\maven\lib\maven3\bin` ) === Preparation before enabling CI === Mainly, the `pom.xml` file needs to be tidy and ready for CI. A good way to check that it is the case, is to look for a good pom example file. For instance check the one in https://github.com/BIOP/ijp-kheops, and modify your pom accordingly. A few things to check: * clean your repository. ** All dependencies should be publicly available, either through scijava maven (https://maven.scijava.org/ - mainly imagej stuff) or through maven central (https://search.maven.org/), or through another publicly available maven repository. ** The dependency versions should : not be a SNAPSHOT dependency (because SNAPSHOTS can be overriden, the build is not reproducible) + their versions should be declared in the properties part of the pom.xml file of the repository. DO NOT WRITE: COUNTEREXAMPLE <dependency> <groupId>org.reflections</groupId> <artifactId>reflections</artifactId> <version>0.9.11</version> </dependency> WRITE: <properties> ... <reflections.version>0.9.11</reflections.version> </properties> <dependency> <groupId>org.reflections</groupId> <artifactId>reflections</artifactId> <version>${reflections.version}</version> </dependency> This allows the versions to be managed / checked and overriden if necessary by scijava maven plugins. ** Take care with javadoc. To test if you did not make any mistake with javadoc, type `mvn javadoc:javadoc`in the intellij terminal (this can take a while). Then correct all the errors (this can take a while also). Warning can be ignored ( thus you can type `mvn javadoc:javadoc | grep error` to avoid displaying warnings, but that works only with git bash, not in the windows terminal`). Usually you have issues with special characters (`<`, `>`, `@`, etc...). You need to replace them with their html representation `&whatever`, see https://dev.w3.org/html5/html-author/charref) === Actionify - enable CI through Github Actions === WARNING: you may want to update your gitignore. Again, check the `.gitignore` file of [https://github.com/BIOP/ijp-kheops](https://github.com/BIOP/ijp-kheops). You can directly copy paste it into your repo. WARNING: Windows may have issues with file permission trakcing. The best is to not track them. For that, execute locally: ``` git config core.fileMode false ``` * Once this is done, you need to run `github-actionify.sh` in simulation mode to see if everything looks right: ** in an explorer window, go to the folder where the pom file of your repo is located. Right-click and execute `git bash here`. Then type `../scijava-scripts/github-actionify.sh`. You may have some issues displayed that you need to fix. If everything looks alright, you can run this command 'for real': ** run `../scijava-scripts/github-actionify.sh -f` to run the actionification for real ** push the repo - which will contain newly generated commits for CI * then Github will run the build and the badge on the github repo will turn green or red depending on the outcome. You can click on the badge to see the build live, and to check if there's any solvable error if the build was not successful == To do for each repository release == Once your repo has been actionified, each time you want to push a release, you need to: ** in an explorer window, go to the folder where the pom file of your repo is located. Right-click and execute `git bash here`. Then type `../scijava-scripts/release-version.sh`. You are asked which version that you want to release. Usually, you are working on a version like v1.2.3-SNAPSHOT, and the script will release the version v1.2.3 and will automatically commit modification in order to update your repo to v1.2.4-SNAPSHOT, where you can continue your development. If this doesn't work, push to GitHub and ask for help! Check `maven.scijava.org` to see if the package has been correctly uploaded.