Skip to content

Latest commit

 

History

History
122 lines (101 loc) · 4.88 KB

README_dev.md

File metadata and controls

122 lines (101 loc) · 4.88 KB
Raw

JudiLing README for future developers

Author: Xuefeng Luo Email: [email protected] Data: June 04, 2021

Project Structure

├── docs
│   ├── build: not uploaded in GitHub, auto-generated by Documenter.jl
│   │   └── ...
│   ├── src: the source code of documentation
│   │   ├── man: manual pages
│   │   │   └── ...: all manual pages
│   │   └── index.md: the index page
│   ├── make.jl: the script to gernerate from src
│   ├── Project.toml
│   ├── Manifest.toml
│   └── pdf_make.jl: the script to gernerate latex format documentation
├── examples: example scripts
│   └── ...
├── src: the source code
│   ├── JudiLing.jl: the entry-point module script
│   └── ...: all other source code scripts
├── test: the test source code
│   ├── data: data for all tests
│   ├── runtests.jl: the entry-point test script
│   └── ...: all other test source code scripts
├── thesis
│   └── (thesis).pdf
├── .gitignore
├── LICENSE
├── Manifest.toml
├── Project.toml
├── README_dev.md
└── README.md

Test, Dev and Production environments

In total, there are three environments. Production environment, development environment and under-construction environment. Production environment is tagged with version numbers. It should be thoroughly tested, carefully maintained and bug-free (well, at least try it). Normally users can download them through add JudiLing in pkg mode. Development environment the master branch in GitHub. It may contain bugs but it is ready to be tested by users. Under-construction environment is any other branches that haven't been merged into master branch. They can be used for checkpoints for the developments.

Development

deploy dev environment locally

Usually, directly cloning JudiLIng from GitHub and writing codes there is not convenient because it is hard to add this into Julia environment. A more sophisticated way to do so is to

  1. create a working dir, for example judiling_dev
  2. add JudiLing in the environment, add JudiLing
  3. clone package locally develop --local Example
  4. update the package, go to dev/JudiLing and git pull
  5. write code in dev/JudiLing and test it through scripts in judiling_dev

Please see more details in:

https://docs.julialang.org/en/v1/stdlib/Pkg/#Pkg

new functions

To develop new functions, please make sure to write corresponding docs and tests for that functions. To test package, run test JudiLing in pkg mode ("]"). To make docs, run make.jl in the docs dir and you can test/verify that docs looks good. On the production side, docs are auto-generate by GitHub action after CI. See .github/workflows/ci.yml for more details.

update new version

  1. update version number in Project.toml ( please make sure the Project.toml file is the one located in the root dir of JudiLing not somewhere else.)
  2. test the functions and docs
  3. push to GitHub and wait for CI script to complete
  4. if NOT pass, fix bugs and repeat steps 2 and 3
  5. if pass, post a new comment under issue "register" with "@JuliaRegistrator register", then wait for Julia registry to pass
  6. if NOT pass (rarely happened), follow the instruction in the Julia registry threads.

test_combo function

test_combo function is a huge monster that contains almost 50 parameters. The workflow is:

  1. prepare datasets in four different modes
  2. create C matrices
  3. create S matrices
  4. calculate/learn F matrices
  5. calculate/learn G matrices
  6. predicting Shat
  7. prediction Chat
  8. learn_paths
  9. build_paths
  10. evaluate
  11. output

==============================================

virtual Environments

  1. Virtual Environment is very import to modern programming projects specially for packages like JudiLing which requires packages of certain versions.
  2. To activate a virtual enviroment for JudiLing. Go to pkg mode ] and then type activate . in Julia repl.
  3. see ref

download and import JudiLing in a local version

  1. In pkg mode ], type develop --local JudiLing.
  2. To verify, in pkg modem type status. There should be a local path like JudiLing v0.5.2 dev\JudiLing under JudiLing version.

dev structure

  1. a dev structure shoule like this:
├── some_other_scripts
├── dev
│   ├── JudiLing
├── Manifest.toml
├── Project.toml

cache mechanism

  1. Julia have cache mechanism. Therefore sometimes you need to quit Julia repl to make new changes taking effect.

dev steps

  1. write code, write doc, write test units
  2. test docs
  3. test test units
  4. upgrade version in Project.tmol
  5. push commits online, wait for CI
  6. add a comment in register issue, "@JuliaRegistrator register" to register in Julia registry.
  7. a new release will be generated by TagBot