= 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 for each repository once, in order to enable CI == === 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! = Legacy c4science Git management system = The c4science git management system has some limitations when compared to github (impossible to download a repo as a zip, no continuous integration). It is however completely handled by EPFL, which is good for data locality ? However since it is possible to create private repository on github for free with an academic affiliation, it is not sure c4science is worth it given the cost of handling two management systems. The documentation below is there for legacy reasons. == On https://c4science.ch/ == There is a Git Management tool on EPFL, https://c4science.ch/ Oli created the [[https://c4science.ch/project/view/567/ | BioImaging And Optics Platform Group]] there and has added all the projects currently under version control. To add a project to **c4science** we need to # Create a new repository following the conventions below. # Change the permissions so that only the members of [[https://c4science.ch/project/view/569/ | ImageJ Tools]] can make changes # Activate the repository # Use the link to push to it from the local repo {F164844, layout=right, float} === Creating a new repository # From the main page, go to **[[https://c4science.ch/diffusion/edit/form/default/| Create A New Repository]]** # Choose **GIT** # Please fill in the fields as suggested by the **Conventions** Section above # Don't forget to add the repository to the right project! The new repository **is not yet active**. You need to first go to **Policies** and change them as follows: - **Visible To**: All Users - **Editable By**: Members of Project// (ImageJ Tools / Imaris Tools...)// - **Can Push**: Members of Project// (ImageJ Tools / Imaris Tools...)// Save and go back to **Basics** and **Activate the Repository** On the right hand menu There is also a page detailing [[c4science/simplerepo| how to create a simple repository]] === Migrating a git.epfl.ch repository === There's a [[c4science/migration | short documentation]] on how to migrate a project initially on https://git.epfl.ch = C4Science VCS Password = In order to push data to C4Science, you need to define a **Version Control System** Password (VCS) 1. Click top right on your icon > select `Settings` . 2. On the left bar, select `VCS password`. Enter a password. 3. Now you can enter the correct password when asked when you push a repo. = Working with multiple remotes for a given repo: GitHub & C4Science = This means you need to be identified with two different accounts. Git is somehow clever because it chooses the right account based on the URL of the remote repository. When you add a remote repository, specify your login. For instance ``` git remote add origin https://chiarutt@c4science.ch/source/bacteriaworkflow.git/ ``` where `chiarutt` is your **c4science login** You will be promted for your **c4science VCS password**. You NEED to specify the password in c4science beforehand NOTE: Don't forget to add your user name before `c4science` If the password was wrongly entered, you can remove it from the OS password manager. In windows 10, it means : execute `Credential Manager` (search with the windows key), then go to Windows Credentials, find the credentials and delete it. Git will re-ask for authentication, and this time you can enter the correct password.