# NPLinker Dev

Author: Cunliang Geng
Created: 2025-03-27

## Topics

### NPLinker Architecture and Codebase (15 minutes)

**Objective**: Understand the high-level architecture and core components.

**Content**:
- **Overall Architecture**: Present a diagram of the system architecture. [Diagrams for compoments](https://nplinker.github.io/nplinker/latest/diagrams/arranger/).
- **Main Components**: Break down modules and their responsibilities ([API doc](https://nplinker.github.io/nplinker/latest/api/nplinker/)).
- **Codebase Organization**: Navigate through the [repository](https://github.com/nplinker/nplinker) structure.
- **NPLinker Next Steps**: Integrate more scoring methods and data types.


### Code Styles and Conventions (20 minutes)

**Objective**: Introduce coding standards for consistency and readability.

**Content**:
- **PEP8 Guidelines**: Introduce [PEP8](https://peps.python.org/pep-0008/) style guide for python code.
- **Naming Conventions**:
- Explain how to name variables (`mode`, `bgc_ids`), functions (`download`, `load_data`), classes (`MibigLoader`) and constants (`DOWNLOADS_DIRNAME`).
- Function arguments: File paths use `file` or `*_file` as argument name, while file names use `filename` or `*_filename`; Same for directories, use `dir` or `*_dir` for path to the directory and `dirname` or `*_dirname` for directory name.
- **Commenting**: Explain how to write comments and introduce special comments for code linting (e.g. `# type: ignore`, `# noqa`).
- **Docstrings**: Introduce [Google docstring style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and [MkDocs features](https://mkdocstrings.github.io/) in docstrings.
- **Static Typing**:
- Emphasize the importance of [static typing](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)
- Introduce the static type checker [Mypy](https://github.com/NPLinker/nplinker/blob/dev/README.dev.md#static-typing).
- How to add missing types for some dependencies (https://github.com/python/typeshed)
- **Linting and Formatting Tool**: Introduce [Ruff](https://github.com/NPLinker/nplinker/blob/dev/README.dev.md#linting-and-formatting).

**Activity**:
- **Quick exercise**: Formatting a piece of code using the introduced tools.

### Testing (15 minutes)

**Objective**: Highlight the role of testing in development.

**Content**:
- **Unit Testing**: Importance of unit tests.
- **Integration Testing**: Importance of integration tests.
- **Testing Tool**: Introduce [pytest](https://docs.pytest.org/en/stable/) and its [plugins](https://docs.pytest.org/en/stable/reference/plugin_list.html).
- **Parallel Testing**: How to run parallel testing with the plugin `pytest-xdist`.
- **Coverage Reports**: How to assess test coverage with the plugins `pytest-cov` and `coverage`.

**Activity**:
- **Run a Unit Test and an Integration Test**: Generate the coverage report.

### Documentation (15 minutes)
**Objective**: Highlight the role of documentation in development.

**Content**:
- **Doc Tool**: Introduce [MkDocs](https://www.mkdocs.org/) and its theme [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
- **Writing Doc**: Use markdown to write doc and docstrings ([syntax reference](https://squidfunk.github.io/mkdocs-material/reference/)).
- **Checking updated doc**: How to [check updated doc locally](https://github.com/NPLinker/nplinker/blob/dev/README.dev.md#docs) on your laptop.
- **Publishing Doc**: How to [publish updated doc](https://github.com/NPLinker/nplinker/blob/dev/README.dev.md#publishing-the-docs) with versioning to Github Page.

**Resources**:
- Mkdocs [reference](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
- Supported [keywords (sections)](https://mkdocstrings.github.io/griffe/reference/docstrings/#sections) in docstring

**Activity**:
- **Generate and View Doc Website Locally**.

### Automated Code Quality Analysis (10 minutes)

**Objective**: Understand how to maintain code quality using automation tools.

**Content**:
- **Continuous Integration (CI)**: The role of CI in development.
- **GitHub Actions**: Overview [GitHub Actions](https://github.com/NPLinker/nplinker/actions) for NPLinker.
- **SonarCloud Integration**: Introduction to [SonarCloud](https://sonarcloud.io/project/overview?id=NPLinker_nplinker) for code analysis.

### Collaborative Development Workflow (20 minutes)

**Objective**: Learn the standard workflow for contributing to NPLinker.

**Content**:
- **Git Branching Model**: Explain `main`, `dev` (default) and feature branches.
- **Issue Tracking**: Show how to use GitHub Issues effectively.
- **Commit Messages**: Best practices for writing clear commit messages.
- **Pull Requests (PRs)**: Process for submitting PRs and how to use [stacked PRs](https://www.stacking.dev/) with the tool [Graphite](https://graphite.dev/) for more efficient PR management.
- **Code Reviews**: Importance and how to perform them constructively.

**Activity**:
- **Live Demonstration**: Create a branch, commit changes, open and review a PR.

### Releasing Python Packages (15 minutes)

**Objective**: Learn how to package and distribute NPLinker.

**Content**:
- **Versioning**: [Semantic versioning](https://semver.org/) principles.
- **Workflow of Releasing**:
1. Pass all tests: make sure all tests have been passed before creating a new release.
2. Update version: `make update-version CURRENT_VERSION=0.0.1 NEW_VERSION=0.0.2`
3. Publish a GitHub release: use [Github action "Draft or publish Github release"](https://github.com/NPLinker/nplinker/actions/workflows/publish_gh_release.yml).
4. Publish to PyPI:
- [GitHub action "Publish to pypi"](https://github.com/NPLinker/nplinker/blob/dev/.github/workflows/publish_to_pypi.yml) should be automaticallly triggered by the new GitHub release.
- Otherwise, you can publish the package manually: `make build` and `make release`

**Activity**:
- **Demonstrate Building and Uploading a Package to TestPyPI**.

### Q&A or Hands-on Development Exercise (30 minutes)

**Objective**: Apply learned concepts in a practical task.

**Content**:
- **Assigned Tasks**: Small issues or feature requests suitable for beginners.

**Activity**:
- **Hands-On Development**: Participants work individually or in pairs to:
- Implement the task.
- Commit and push changes to a new branch.
- Create a pull request for review.