From 191ae8c25ed21b8f35594fc4f6540c35ad3ea759 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludwig=20H=C3=BClk?= Date: Thu, 5 Dec 2024 00:12:12 +0100 Subject: [PATCH 1/3] Update docs #34 --- .../continuous-integration/usage.md | 4 +- docs/development/git/index.md | 52 ++++--------------- mkdocs.yml | 5 +- 3 files changed, 16 insertions(+), 45 deletions(-) diff --git a/docs/development/continuous-integration/usage.md b/docs/development/continuous-integration/usage.md index 08a2c9d..1c685d4 100644 --- a/docs/development/continuous-integration/usage.md +++ b/docs/development/continuous-integration/usage.md @@ -3,7 +3,7 @@ ## Add new code test To add a new test for any new functionality you have added or you plan to add you should add a test. -The test is imply added to the tests/ +The test is implied added to the tests/ directory. See our examples .... @@ -25,6 +25,6 @@ Running this command will generate a comprehensive report, which may require som For remote debugging, you can monitor the status of your automation jobs in two ways: 1. Create a pull request and view the CI status integration there. -2. Visit the [Actions tab of your repository](https://github.com/rl-institut/super-repo/actions) to see all available job executions. +2. Visit the [Actions tab of your repository](https://github.com/rl-institut/super-repository/actions) to see all available job executions. These options allow you to closely monitor the progress and outcomes of your CI workflow, ensuring the reliability and quality of your codebase. diff --git a/docs/development/git/index.md b/docs/development/git/index.md index 5f7f886..3e03571 100644 --- a/docs/development/git/index.md +++ b/docs/development/git/index.md @@ -29,10 +29,10 @@ For more information about how `.gitignore` files work, see the [Ignoring Files [Issue Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) offer specific functions and default configurations for new issues. -- [Feature Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_feature.md) -- [Bug Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_bug.md) -- [Release Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_release.md) -- [User Kudos Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_user_kudos.md) +- [Feature Issue](https://github.com/rl-institut/super-repository/blob/production/.github/ISSUE_TEMPLATE/issue_template_feature.md) +- [Bug Issue](https://github.com/rl-institut/super-repository/blob/production/.github/ISSUE_TEMPLATE/issue_template_bug.md) +- [Release Issue](https://github.com/rl-institut/super-repository/blob/production/.github/ISSUE_TEMPLATE/issue_template_release.md) +- [User Kudos Issue](https://github.com/rl-institut/super-repository/blob/production/.github/ISSUE_TEMPLATE/issue_template_user_kudos.md) ## Pull Request (PR) Template @@ -43,45 +43,12 @@ It includes all needed information to merge branches and release new versions. ## GitHub Labels GitHub Labels are used to organize Issues and PR.
-Colours and emoticons improve presentation. - -Categories: - -- **type**: - - bug :bug: "Something isn't working" [default] #FEF1C7 - - feature :hammer_and_wrench: "New feature or request" #FEF1C7 - - enhancement :gear: "Improvement of an existing feature" [default] #FEF1C7 - - question :question: "Further information is requested" [default] #FEF1C7 - - release :rocket: "Release procedure" #FEF1C7 -- **part**: - - backend :bricks: "Backend component" #A7F3D5 - - frontend :desktop_computer: "Improvement of design or content" #A7F3D5 - - docu :book: "Improvements or additions to documentation" [default] #A7F3D5 - - github :octocat: "Improvement of the organisation or repo" #A7F3D5 - - community :earth_africa: "Concerns the community" #A7F3D5 -- **status**: - - active :construction: "Work in progress" #93C5FD - - discussion :speech_balloon: "Discussion is ongoing" #93C5FD - - blocked :stop_sign: "Blocked or impeded progress" #F9A8D4v - - decision wanted :ballot_box: "Decision is needed" #F9A8D4 - - completed :heavy_check_mark: "Task has been completed" #6EE7B7 -- **priority**: - - low :sloth: "Low priority" #FCD34D - - high :zap: "High priority" #FDBA74 - - critical :fire: "Critical priority" #FCA5A5 -- resolution: - - released :tada: "Resolved and released" #ECDCF8 - - wontfix :no_entry: "This will not be worked on" [default] #ECDCF8 - - invalid :x: "Issue is invalid" [default] #ECDCF8 - - duplicate :feet: "This issue or pull request already exists" [default] #ECDCF8 -- other: - - good first issue :seedling: "Good for newcomers" [default] #EBF0F3 - - help wanted :raising_hand: "Help or assistance is needed" [default] #EBF0F3 - - example :triangular_ruler: "Provides an example" #EBF0F3 +Colours and emoticons improve presentation, see:
+πŸ“ [github-labels.json](https://github.com/rl-institut/super-repository/blob/develop/docs/development/git/github-labels.json) ## GitHub Workflows (Actions) -[GitHub Actions](https://github.com/rl-institut/super-repo/actions) +[GitHub Actions](https://github.com/rl-institut/super-repository/actions) are used to automate processes of the repository.
Main use-cases are building and publishing the documentation and run automated tests. @@ -127,5 +94,8 @@ To run the hooks on all files in your repository use:
!!! warning "Markdown files / Admonitions" If the hook is applied to markdown files that include special formatting, - (e.g. `mkdocs.yml`), this can introduce incorrect changes.
+ (for example `mkdocs.yml`), this can introduce incorrect changes. This effects [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) boxes for MkDocs. + +!!! note "Used Icons" + πŸ™ GitHub | πŸ’  git | πŸ“ File | πŸ’» Command Line diff --git a/mkdocs.yml b/mkdocs.yml index 4de1917..aca4e00 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,8 @@ extra_css: nav: - Home: index.md - Development: + - Documentation: + - development/documentation/index.md - Collaboration: - development/collaboration/index.md - License and Citation: development/collaboration/license_and_citation.md @@ -79,8 +81,7 @@ nav: - development/continuous-integration/index.md - Code Style: - code/style/index.md - - Documentation: - - development/documentation/index.md + - Release: - development/release/index.md - Code Documentation: From 8387ed9112270aba7c090015d90088cecb60c8ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludwig=20H=C3=BClk?= Date: Fri, 6 Dec 2024 01:02:19 +0100 Subject: [PATCH 2/3] Update documentation #34 --- .../best-practice/code_style.md} | 16 +- .../best-practice/continuous_integration.md | 128 ++++++++++++++ docs/development/best-practice/index.md | 23 +++ .../best-practice/pre_commit_hooks.md | 26 +++ .../test-driven-development-workflow.md | 123 ------------- .../best-practice/test_driven_development.md | 167 ++++++++++++++++++ .../{git/index.md => collaboration/git.md} | 9 +- .../{git => collaboration}/github-labels.json | 0 .../continuous-integration/index.md | 98 ---------- .../setup_github_actions.md | 24 --- .../continuous-integration/setup_tox.md | 65 ------- .../continuous-integration/usage.md | 30 ---- docs/development/documentation/index.md | 12 +- docs/development/release/index.md | 13 +- docs/{css => }/extra.css | 0 .../code_example.md | 0 docs/{code => user_documentation}/index.md | 0 .../install/index.md | 0 mkdocs.yml | 23 ++- 19 files changed, 373 insertions(+), 384 deletions(-) rename docs/{code/style/index.md => development/best-practice/code_style.md} (75%) create mode 100644 docs/development/best-practice/continuous_integration.md create mode 100644 docs/development/best-practice/pre_commit_hooks.md delete mode 100644 docs/development/best-practice/test-driven-development-workflow.md create mode 100644 docs/development/best-practice/test_driven_development.md rename docs/development/{git/index.md => collaboration/git.md} (89%) rename docs/development/{git => collaboration}/github-labels.json (100%) delete mode 100644 docs/development/continuous-integration/index.md delete mode 100644 docs/development/continuous-integration/setup_github_actions.md delete mode 100644 docs/development/continuous-integration/setup_tox.md delete mode 100644 docs/development/continuous-integration/usage.md rename docs/{css => }/extra.css (100%) rename docs/{code => user_documentation}/code_example.md (100%) rename docs/{code => user_documentation}/index.md (100%) rename docs/{code => user_documentation}/install/index.md (100%) diff --git a/docs/code/style/index.md b/docs/development/best-practice/code_style.md similarity index 75% rename from docs/code/style/index.md rename to docs/development/best-practice/code_style.md index 3854741..58c1525 100644 --- a/docs/code/style/index.md +++ b/docs/development/best-practice/code_style.md @@ -8,22 +8,21 @@ Maintaining a consistent code style is crucial for the readability and maintainability of a Python project. We enforce most of the following guidelines in our -[Continuous-Integration pipeline](../../development/continuous-integration/index.md) +[Continuous-Integration pipeline](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/) that check the code automatically. ## 1. Installation Before contributing to the project, make sure you have the necessary tools installed for code style enforcement. -We utilize [pre-commit](https://github.com/pre-commit/pre-commit-hooks) +We utilize [pre-commit](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/) to automate code checks before committing changes. -To install and setup pre-commit, see [Continuous-Integration pipeline](../../development/git/#pre-commit) ## 2. Code Formatting Consistent code formatting enhances readability and reduces unnecessary debates about style. -We use [Black](https://github.com/psf/black) as our Python code formatter. +We use [Ruff](https://github.com/astral-sh/ruff) as Python code formatter. It automatically formats your code to adhere to the project's style guidelines. ## 3. Naming Conventions @@ -45,14 +44,7 @@ Use comments to explain complex logic and docstrings to describe functions, classes, and modules. Following good documentation practices ensures code is understandable to others. -## 6. Imports - -Our imports are automatically checked and sorted using -[isort](https://github.com/pycqa/isort). -This tool organizes imports based on the Black code style and optimizes import -statements for readability. - -## 7. Code Structure and Organization +## 6. Code Structure and Organization Maintain a logical structure within files, grouping related functions and classes. Consider the readability of your code and strive for modular, diff --git a/docs/development/best-practice/continuous_integration.md b/docs/development/best-practice/continuous_integration.md new file mode 100644 index 0000000..2246916 --- /dev/null +++ b/docs/development/best-practice/continuous_integration.md @@ -0,0 +1,128 @@ +# Continuous Integration (CI) and Test Automation + +Continuous Integration (CI) ensures consistent code quality through automated +testing, reporting, and deployments.
+Our setup combines `GitHub Actions` and `tox` to streamline testing across +environments, making the process robust and efficient. + +## GitHub Actions: Workflows + +GitHub Actions automates key workflows like testing, linting, and code +quality checks. The CI pipeline includes the following tasks: +- **Unit Testing**: Using `pytest` to ensure comprehensive test coverage. +- **Code Formatting**: Validating syntax with `ruff`. +- **Linting**: Verifying code style and docstrings with `ruff.lint`. +- **Import Sorting**: Organizing imports with `ruff.lint.isort`. + +To set up GitHub Actions workflows for the repository, +follow the [official GitHub guide](https://docs.github.com/en/actions/guides).
+The GitHub Actions workflow is triggered on pull requests or commits to +the `develop` or `production` branches. +1. **Setup**: Prepares a Python environment and installs dependencies. +2. **Testing**: Executes the `tox` automation suite to run the defined tests. +3. **Reporting**: Generates detailed failure reports for debugging. + +GitHub Actions also automates documentation updates, ensuring the latest +changes from the `develop` branch are reflected. For more details, see +the [official GitHub Actions guide](https://docs.github.com/en/actions/guides). + + +## Tox: Automating Testing + +[`tox`](https://tox.wiki/en/stable/) is a versatile tool for managing test +environments and automating testing tasks across Python versions and operating +systems (Linux, macOS, Windows).
+It enhances reproducibility and reliability by creating isolated environments +for testing: + +- **Virtual Environments**: Isolates dependencies for each Python version. +- **Automated Testing**: Runs tests and style checks (for example, `pytest`, `ruff`). +- **Cross-Version/Platform Testing**: Ensures compatibility across Python versions and operating systems. +- **Dependency Management**: Customizes dependencies for diverse test scenarios. +- **Reproducibility**: Maintains consistent workflows by way of πŸ“ `tox.ini`. +- **Extensibility**: Supports plugins for custom functionality. + +### Install + +Install the required package in a python environment.
+πŸ’» `pip install tox` install tox
+πŸ’» `tox` run tox locally + + +## Adding and Managing Tests + +New tests should be placed in the πŸ“ `tests/` directory. For example: +- Add a test to validate new functionality. +- Use `pytest` for unit tests, or extend πŸ“ `tox.ini` for additional test configurations. + +By combining `tox` and GitHub Actions, our CI pipeline ensures robust, +reproducible, and scalable testing workflows. + +### Test Patterns + +1. **Unit and Integration Test** + - **Purpose**: Test individual functions or methods. + - **Framework**: `unittest`, `pytest` + - **Example**: Simple function test and external API interactions. + +2. **Functional Testing** + - **Purpose**: Test complete functionality (end-to-end). + - **Framework**: `pytest`, `selenium` + - **Example**: Test user login in a web app. + +3. **Mocking** + - **Purpose**: Simulate external dependencies. + - **Framework**: `unittest.mock`, `pytest-mock` + - **Example**: Mock API calls in tests. + +4. **Acceptance Testing** + - **Purpose**: Verify the software meets requirements. + - **Framework**: `pytest`, `Behave` + - **Example**: Verify login form functionality. + +5. **Performance Testing** + - **Purpose**: Measure performance under load. + - **Framework**: `pytest-benchmark`, `locust` + - **Example**: Measure function execution time. + +6. **Security Testing** + - **Purpose**: Test for security vulnerabilities. + - **Framework**: `bandit` + - **Example**: Scan for hardcoded passwords. + +7. **Snapshot Testing** + - **Purpose**: Compare outputs to saved snapshots. + - **Framework**: `pytest-snapshot` + - **Example**: Compare function output snapshots. + +8. **Property-Based Testing** + - **Purpose**: Test properties of functions with random inputs. + - **Framework**: `hypothesis` + - **Example**: Test that a sorting function always returns a sorted list. + +### Examples + +The file πŸ“ `tests/test_example.py` contains basic examples for the functions in
+πŸ“ `super_repo/test_calculator.py`. + +In Python, the `assert` statement is used to test if a condition is true.
+If the condition is false, an AssertionError is raised, indicating the test failed. + +```python +result = add(3, 4) +assert result == 7 +``` + +The `raises` context manager from the `pytest` library ensures that a ValueError is raised.
+The `match` argument specifies that the error message matches the expected error pattern. + +```python +with raises(ValueError, match=r"Cannot divide by zero"): + divide(15, 0) +``` + +We encourage contributions of additional tests and examples to help improve +coverage and showcase different use casesβ€”your input is valuable to enhancing the project! + +!!! note "Used Icons" + πŸ™ GitHub | πŸ’  git | πŸ“ File | πŸ’» Command Line diff --git a/docs/development/best-practice/index.md b/docs/development/best-practice/index.md index e69de29..58bd154 100644 --- a/docs/development/best-practice/index.md +++ b/docs/development/best-practice/index.md @@ -0,0 +1,23 @@ +# Best Practices + +Adopting best practices in software development enhances code quality, +maintains consistency, and ensures reliability.
+This section focuses on three key methodologies essential for maintaining +high standards in a collaborative scientific software environment: + +- [**Continuous Integration (CI)**](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/):
+ Automating the integration of code changes to catch errors early and maintain a stable codebase. + CI ensures that all contributions are rigorously tested and integrated seamlessly into the project. + +- [**Test-Driven Development (TDD)**](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/):
+ A methodology where tests are written before the actual code implementation.
+ TDD promotes robust and well-designed code by enforcing that each feature is accompanied by + thorough testing from the outset. + +- [**Pre-commit Hooks (PCH)**](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/):
+ Tools to enforce code + quality and consistency by running checks or scripts before changes are committed.
+ These hooks help identify issues early, improving code hygiene and reducing technical debt. + +Following these practices will streamline development, reduce bugs, and foster a +productive, collaborative coding environment. diff --git a/docs/development/best-practice/pre_commit_hooks.md b/docs/development/best-practice/pre_commit_hooks.md new file mode 100644 index 0000000..9dd560c --- /dev/null +++ b/docs/development/best-practice/pre_commit_hooks.md @@ -0,0 +1,26 @@ +# Pre-commit Hooks + +Pre-commit hooks are tools used to enforce code quality and consistency by
+running checks or scripts before changes are committed.
+These hooks help identify issues early, improving code hygiene. + +## Installation and Setup + +Install the package in your base environment. + πŸ’» `pip install pre-commit` + +Create a πŸ“ `.pre-commit-config.yaml` file in your repository root.
+This file defines the hooks and configurations. + +## Usage + +To run the hooks manually, use:
+ πŸ’» `pre-commit run --all-files` + +Now, every time you commit changes, the pre-commit hooks will automatically
+run the checks defined in your configuration file, ensuring code quality before +committing. + + +!!! note "Used Icons" + πŸ™ GitHub | πŸ’  git | πŸ“ File | πŸ’» Command Line diff --git a/docs/development/best-practice/test-driven-development-workflow.md b/docs/development/best-practice/test-driven-development-workflow.md deleted file mode 100644 index 7617bed..0000000 --- a/docs/development/best-practice/test-driven-development-workflow.md +++ /dev/null @@ -1,123 +0,0 @@ -# Test-Driven Development - -The Test-Driven Development can be used for any code project. - -When adding new functionality or features, write tests for them first before implementing the new functionality. This ensures that your changes don't affect existing functionality and that all functions work as expected. - -## Example: Implement a test case and functionality to test a django app - -The following example shows how to implement the testing technique in a Django app. - -!!! Info - You can run all test in django by running: - - ```bash - python manage.py test - ``` - - To tun specific test cases you have to provide the app name followed by the name of the test case. - In the example below the command would look like this: - - ```bash - python manage.py test app.MyModelViewTestCase - ``` - -### 1. Step - -First, make sure you have an Django app that you want to test. - -### 2. Step - -Next, write a test for a function or feature you want to implement. Let's say you want to implement a view that returns a list of objects from the database. You also need a model to represent the database table object. A possible test could look like this: - -app/tests/my_test.py - -```python -from django.test import TestCase -from myapp.models import MyModel - -class MyModelViewTestCase(TestCase): - def test_list_view_displays_all_objects(self): - MyModel.objects.create(name="object1") - MyModel.objects.create(name="object2") - response = self.client.get('/my-models/') - self.assertEqual(response.status_code, 200) - self.assertContains(response, "object1") - self.assertContains(response, "object2") - -``` - -### 3. Step - -Run the test to make sure it fails because the view has not been implemented yet. - -```bash -python manage.py test -``` - -### 4. Step - -Implement the model and view to make the test pass. - -models.py - -```python -from django.db import models - -class MyModel(models.Model): - name = models.CharField(max_length=255) - created_at = models.DateTimeField(auto_now_add=True) - - def __str__(self): - return self.name -``` - -views.py - -```python -from django.views.generic import ListView -from myapp.models import MyModel - -class MyModelListView(ListView): - model = MyModel - template_name = "myapp/my_model_list.html" - -``` - -### 5. Step - -Run the test again to make sure it passes. - -```bash -python manage.py test -``` - -### 6. Step - -Write additional tests to make sure the view works as expected. - -```python -class MyModelViewTestCase(TestCase): - def test_list_view_displays_all_objects(self): - MyModel.objects.create(name="object1") - MyModel.objects.create(name="object2") - response = self.client.get('/my-models/') - self.assertEqual(response.status_code, 200) - self.assertContains(response, "object1") - self.assertContains(response, "object2") - - def test_list_view_displays_empty_message(self): - response = self.client.get('/my-models/') - self.assertEqual(response.status_code, 200) - self.assertContains(response, "No objects found.") - - -``` - -### 7. Step - -Run all the tests to make sure they all pass. - -```bash -python manage.py test -``` diff --git a/docs/development/best-practice/test_driven_development.md b/docs/development/best-practice/test_driven_development.md new file mode 100644 index 0000000..5a2a719 --- /dev/null +++ b/docs/development/best-practice/test_driven_development.md @@ -0,0 +1,167 @@ +# Test-Driven Development + +Test-Driven Development (TDD) is a software development methodology that +emphasizes writing tests before implementing the corresponding functionality.
+This approach ensures that new changes do not unintentionally break existing +features and that all functions perform as expected. + +## Code Coverage + +Code coverage is a metric used in software testing that helps determine +the percentage of code that is exercised by tests.
+It is an essential tool for assessing the effectiveness of your test suite. +High code coverage generally indicates that most of your code has been tested, +while lower coverage can suggest that some parts of the application may be +under-tested, potentially leading to hidden bugs or vulnerabilities. + +[Codecov.io](https://codecov.io/) is a popular tool for tracking and +visualizing code coverage. It integrates with various CI/CD pipelines and +allows developers to upload their coverage reports.
+Once integrated, Codecov provides detailed insights into code coverage trends, +coverage gaps, and areas that require further testing. + +To integrate Codecov with your project, follow these steps: + +1. Install pytest
+ πŸ’» `pip install pytest pytest-cov` install pytest + +2. Add GitHub Action
+ πŸ“ `.github/workflows/codecov.yml` + +3. Create an account +Create a Codecov account at [Codecov.io](https://about.codecov.io/) and link your repository. + +4. Upload the Coverage Report +After running your tests with coverage, upload the results to Codecov.
+This is done automatically through the CI configuration. + +5. View Coverage Reports +Once your coverage report is uploaded, you can view detailed insights and trends +on the Codecov dashboard. + +6. Code Coverage Badge +A coverage badge provides a visual indication of the test coverage for the +πŸ“ `README.rst` page. It is updated automatically as new reports are uploaded to Codecov. + +While code coverage is a valuable metric for identifying untested code, +high coverage does not necessarily indicate high-quality tests. +It only measures the quantity of code exercised during testing, not the quality +or effectiveness of those tests. Tests can pass without actually verifying +correct behavior, and some areas of the code may be covered by trivial tests +that do not expose potential issues. Relying solely on coverage can lead to a +false sense of security and might divert attention from other important aspects +of testing, such as edge cases and integration scenarios. + +## Example: Implementing Test Cases for a Django App + +This example demonstrates the TDD approach within a Django app.
+You can run all tests in Django using the following command: + +πŸ’» `python manage.py test` + +To run specific test cases, you can provide the app name and the test case: + +πŸ’» `python manage.py test app.MyModelViewTestCase` + +This is a Step-by-Step Guide to TDD in Django: + +### 1. Set Up the Django App + +Ensure that you have a Django app in place that you wish to test. + +### 2. Write a Test for the New Feature + +Begin by writing a test for the functionality you intend to implement. +For example, if you need to create a view that returns a list of objects from +the database, and a corresponding model to represent the database table, +your test might look like this:
+ πŸ“ `app/tests/my_test.py`: + +```python +from django.test import TestCase +from myapp.models import MyModel + +class MyModelViewTestCase(TestCase): + def test_list_view_displays_all_objects(self): + MyModel.objects.create(name="object1") + MyModel.objects.create(name="object2") + response = self.client.get('/my-models/') + self.assertEqual(response.status_code, 200) + self.assertContains(response, "object1") + self.assertContains(response, "object2") +``` + +### 3. Run the Test + +At this point, run the test to confirm it fails, as the view has not been implemented yet.
+ πŸ’» `python manage.py test` + +### 4. Implement the Model and View + +Implement the model and view to make the test pass. + +πŸ“ `models.py`: + +```python +from django.db import models + +class MyModel(models.Model): + name = models.CharField(max_length=255) + created_at = models.DateTimeField(auto_now_add=True) + + def __str__(self): + return self.name +``` + +πŸ“ `views.py`: + +```python +from django.views.generic import ListView +from myapp.models import MyModel + +class MyModelListView(ListView): + model = MyModel + template_name = "myapp/my_model_list.html" + +``` + +### 5. Run the Test Again + +Run the tests again to ensure the changes pass the test.
+ πŸ’» `python manage.py test` + +### 6. Add Additional Tests + +Write additional tests to verify that the view works as expected.
+For example, you can test for empty responses: + +```python +class MyModelViewTestCase(TestCase): + def test_list_view_displays_all_objects(self): + MyModel.objects.create(name="object1") + MyModel.objects.create(name="object2") + response = self.client.get('/my-models/') + self.assertEqual(response.status_code, 200) + self.assertContains(response, "object1") + self.assertContains(response, "object2") + + def test_list_view_displays_empty_message(self): + response = self.client.get('/my-models/') + self.assertEqual(response.status_code, 200) + self.assertContains(response, "No objects found.") +``` + +### 7. Run All Tests + +Finally, run all the tests to ensure they pass successfully:
+ πŸ’» `python manage.py test` + +### Conclusion + +TDD provides a structured approach to writing reliable, maintainable software. +By ensuring that tests are written before implementing functionality, +developers can be confident that new changes will not introduce unintended +side effects and that the codebase remains functional and robust over time. + +!!! note "Used Icons" + πŸ™ GitHub | πŸ’  git | πŸ“ File | πŸ’» Command Line diff --git a/docs/development/git/index.md b/docs/development/collaboration/git.md similarity index 89% rename from docs/development/git/index.md rename to docs/development/collaboration/git.md index 3e03571..8fb5c67 100644 --- a/docs/development/git/index.md +++ b/docs/development/collaboration/git.md @@ -22,7 +22,7 @@ The majority of the development will be done in `feature` branches. This file specifies intentionally untracked files to ignore.
It is copied from [a collection of .gitignore templates](https://github.com/github/gitignore).
-For more information about how `.gitignore` files work, see the [Ignoring Files chapter](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) of the Pro Git book. +For more information about how πŸ“ `.gitignore` files work, see the [Ignoring Files chapter](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) of the Pro Git book. ## Issue Templates @@ -55,7 +55,8 @@ Main use-cases are building and publishing the documentation and run automated t ## Pre-commit **Pre-commit** is a tool to easily setup and run `pre-commit hooks` for your git repository.
-See the documentation of [pre-commit](https://pre-commit.com/) for further information.
+See the best-practice documentation of [pre-commit]() or the +[official documentation](https://pre-commit.com/) for further information.
It is used to improve auto-format code, do linting and run tests before every commit. ### Install @@ -66,7 +67,7 @@ Install the required package in a python environment.
### Setup -The hooks are configured in the `.pre-commit-config.yaml` file.
+The hooks are configured in the file πŸ“ `.pre-commit-config.yaml`.
List of implemented hooks: - [Pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks) - Out-of-the-box hooks @@ -94,7 +95,7 @@ To run the hooks on all files in your repository use:
!!! warning "Markdown files / Admonitions" If the hook is applied to markdown files that include special formatting, - (for example `mkdocs.yml`), this can introduce incorrect changes. + (for example πŸ“ `mkdocs.yml`), this can introduce incorrect changes. This effects [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) boxes for MkDocs. !!! note "Used Icons" diff --git a/docs/development/git/github-labels.json b/docs/development/collaboration/github-labels.json similarity index 100% rename from docs/development/git/github-labels.json rename to docs/development/collaboration/github-labels.json diff --git a/docs/development/continuous-integration/index.md b/docs/development/continuous-integration/index.md deleted file mode 100644 index 428f8b9..0000000 --- a/docs/development/continuous-integration/index.md +++ /dev/null @@ -1,98 +0,0 @@ -# Continuous Integration - -Continuous Integration (CI) is a good practice in software development that -involves automated testing of code, ensuring repository quality, reporting, and -automate deployments.
-The process involves the utilization of multiple technologies. -Once the setup is complete, it's possible to create new test and -also to interpret the output of success or error messages as response from the -test-execution. A brief summary of this process is also provided for reference. - -## Automation - -The package [tox](https://github.com/tox-dev/tox) automates the process of testing -Python projects. It provides support for creating and managing test environments -across cross different environments, Python versions, and dependencies.
-It ensures that the code is reliable, functional, and compatible on different -computers leading to higher code quality and more robust software. -Combined with GitHub Actions, it allows you to automate a wide range of tasks. - -### Key features and functionalities - -For each specified Python version, tox creates isolated virtual environments. -This is important because different projects might have different dependencies -or require specific Python versions and run on different platforms like Windows, Linux, or MacOS. -Isolation prevents conflicts between packages used by different projects. - -1. **Virtual Environments**: Tox creates isolated virtual environments for each specified Python version. This is crucial because different projects might have different dependencies or require specific Python versions. Isolation prevents conflicts between packages used by different projects. -2. **Automated Testing**: Tox automates the entire testing process. It can be configured to run various types of tests, such as unit tests, integration tests, and even style checks. This ensures that the project is thoroughly tested in different environments without manual intervention. -3. **Cross-Version and Cross-Platform Testing**: Tox enables you to test your code against multiple versions of Python, including Python 2 and Python 3. Additionally, it supports testing on various operating systems, allowing you to identify and address compatibility issues specific to different platforms. -4. **Dependency Management**: Tox can help manage project dependencies by allowing you to specify different sets of dependencies for different testing environments. This helps ensure that your code works with different combinations of dependencies. -5. **Configuration via tox.ini**: Tox uses a configuration file named `tox.ini` to define testing environments, dependencies, and testing commands. This file also allows you to set up various testing environments, customize test commands, and control other testing-related behaviors. -6. **Consistency and Reproducibility**: Tox aids in maintaining consistency and reproducibility in your testing process. By setting up a standard testing workflow and environments, you reduce the risk of inconsistent results due to differences in developers' local setups. -7. **Continuous Integration (CI)**: Tox is often used in conjunction with CI systems like Jenkins, Travis CI, CircleCI, and GitHub Actions. By incorporating Tox into your CI pipeline, you can ensure that your code is automatically tested in multiple environments whenever changes are pushed to the repository. -8. **Plugin System**: Tox has a plugin system that allows for extensibility. This means you can add custom functionality to the testing process, such as additional test runners, code analysis tools, and more. - -## Install - -Install the required package [`tox`](https://tox.wiki/en/stable/installation.html) in a python environment.
-πŸ’» `pip install tox` install tox
- -## Setup - -Configuring `tox` may involve some complexity.
-See the official [tox user guide](https://tox.wiki/en/stable/user_guide.html) for further information. - -All test stages are setup in the configuration file `tox.ini`. -This file configures all test environments as well as the tools and configuration -used to run tests and checks. - -## Testing - -### pytest - -For smaller projects or a more straightforward approach, -testing can also be effectively accomplished using [pytest](https://github.com/pytest-dev/pytest/). -This allows for efficient testing without the additional complexity of setting -up and managing multiple environments. - -### black - -Checking code syntax with `black` - -### flake8 - -Verifying `docstrings` with `flake8` - -### isort - -Sorting imports with `isort` - -### Django tests - -Testing Django projects with [Django tests](https://docs.djangoproject.com/en/3.2/topics/testing/). - -## GitHub Actions - -GitHub offers an integrated CI called `GitHub Actions`, -which enables the definition of test workflows and events. -These workflows can be executed, for instance, -with every pull request or new commit on a specific branch. -To set up workflows for your repository, follow the [Guides for GitHub Actions](https://docs.github.com/en/actions/guides). - -### Automated Testing - -All tests are defined within the workflow file `.github/workflows/automated-testing.yml`. -The workflow defines the tasks for a action, and a runner executes these tasks on a -virtual machine provided by GitHub. - -The workflow is triggered whenever there's a pull request or a commit to the `develop` or `production` branches. -The workflow prepares the Python environment and installs relevant dependencies before executing the `tox` automation suite. -If any errors are detected, the workflow fails and generates a detailed report for developers to review. - -### Building and deploying the documentation - -Another use case that involves the GitHub-Actions is the automated deployment of the documentation. -While all minor versions are manually deployed using [mike](https://rl-institut.github.io/super-repo/latest/development/documentation/#mike). -GitHub-Actions workflow builds and deploys the `develop` branch. -This ensures that the documentation is automatically updated if a new feature or update is available. diff --git a/docs/development/continuous-integration/setup_github_actions.md b/docs/development/continuous-integration/setup_github_actions.md deleted file mode 100644 index cc70bc1..0000000 --- a/docs/development/continuous-integration/setup_github_actions.md +++ /dev/null @@ -1,24 +0,0 @@ -# Configure Continuous Integration using GitHub Actions - -## What is included in the tests? - -Our continuous integration (CI) process executes a series of tests, including -running `pytest` and performing linting and code quality checks. - -Here's an overview of the tasks involved in our example: - -- Running `pytest` -- Checking code syntax with `black` -- Verifying `docstrings` with `flake8` -- Sorting imports with `isort` - -All these tools are executed as part of a job defined within a GitHub Actions workflow file. -The workflow defines the tasks for a job, and a runner executes these tasks on a -virtual machine provided by GitHub. - -!!! Info "Setup GitHub Actions" - To set up GitHub Actions workflows for your repository, follow the [official GitHub guide](https://docs.github.com/en/actions/guides). - -Our CI workflow is triggered whenever there's a pull request or a commit to the `develop` or `production` branches. -The workflow prepares the Python environment and installs relevant dependencies before executing the `tox` automation suite. -If any errors are detected, the workflow fails and generates a detailed report for developers to review. diff --git a/docs/development/continuous-integration/setup_tox.md b/docs/development/continuous-integration/setup_tox.md deleted file mode 100644 index e86789e..0000000 --- a/docs/development/continuous-integration/setup_tox.md +++ /dev/null @@ -1,65 +0,0 @@ -# Configure Tox test-automation - -To streamline our test environment setup, we use `tox`, a powerful tool that -automates testing across different environments. - -!!! Note - [Tox](https://tox.wiki/en/stable/) is a powerful tool that simplifies - and automates the process of testing Python projects across different environments. - It ensures that your code is reliable, functional, and compatible with various - Python versions and dependencies, ultimately leading to higher code quality - and more robust software. Combined with a runner like GitHub Actions, - it allows you to automate a wide range of tasks. - - ??? Info "Key features and functionalities" - - Tox creates isolated virtual environments for each specified Python version. This is crucial because different projects might have different dependencies or require specific Python versions. Isolation prevents conflicts between packages used by different projects. - - 1. **Virtual Environments**: Tox creates isolated virtual environments for each specified Python version. This is crucial because different projects might have different dependencies or require specific Python versions. Isolation prevents conflicts between packages used by different projects. - - 2. **Automated Testing**: Tox automates the entire testing process. It can be configured to run various types of tests, such as unit tests, integration tests, and even style checks. This ensures that the project is thoroughly tested in different environments without manual intervention. - - 3. **Cross-Version and Cross-Platform Testing**: Tox enables you to test your code against multiple versions of Python, including Python 2 and Python 3. Additionally, it supports testing on various operating systems, allowing you to identify and address compatibility issues specific to different platforms. - - 4. **Dependency Management**: Tox can help manage project dependencies by allowing you to specify different sets of dependencies for different testing environments. This helps ensure that your code works with different combinations of dependencies. - - 5. **Configuration via tox.ini**: Tox uses a configuration file named `tox.ini` to define testing environments, dependencies, and testing commands. This file also allows you to set up various testing environments, customize test commands, and control other testing-related behaviors. - - 6. **Consistency and Reproducibility**: Tox aids in maintaining consistency and reproducibility in your testing process. By setting up a standard testing workflow and environments, you reduce the risk of inconsistent results due to differences in developers' local setups. - - 7. **Continuous Integration (CI) Integration**: Tox is often used in conjunction with CI systems like Jenkins, Travis CI, CircleCI, and GitHub Actions. By incorporating Tox into your CI pipeline, you can ensure that your code is automatically tested in multiple environments whenever changes are pushed to the repository. - - 8. **Plugin System**: Tox has a plugin system that allows for extensibility. This means you can add custom functionality to the testing process, such as additional test runners, code analysis tools, and more. - -## What is included in the tests? - -Here's an overview of the testing-tasks involved: - -- Running `pytest` -- Checking code syntax with `black` -- Verifying `docstrings` with `flake8` -- Sorting imports with `isort` - -!!! Info "Run test on multiple platforms" - Our Tox environments are executed on all major platforms including windows, linux and macos. - -## Installation - -Begin by installing [`tox`](https://tox.wiki/en/stable/installation.html): - -```bash -pip install tox -``` - -!!! Note - Setup and activate a [python environment](https://docs.python.org/3/library/venv.html) first. - -## Setup - -Configuring `tox` may involve some complexity. -Start by defining what tests you want to run and what dependencies -(such as packages or external services) are required for the tests. -Organize these test tasks into logical steps. - -!!! Info "Tox User Guide" - The official [tox User Guide](https://tox.wiki/en/stable/user_guide.html) diff --git a/docs/development/continuous-integration/usage.md b/docs/development/continuous-integration/usage.md deleted file mode 100644 index 1c685d4..0000000 --- a/docs/development/continuous-integration/usage.md +++ /dev/null @@ -1,30 +0,0 @@ -# Usage - -## Add new code test - -To add a new test for any new functionality you have added or you plan to add you should add a test. -The test is implied added to the tests/ -directory. - -See our examples .... - -## Debugging - -### Local Debugging - -You can run your automation suite locally by typing the following command in your console. This is useful for verifying the outcome of your automation pipeline before pushing your code: - -```bash -tox -``` - -Running this command will generate a comprehensive report, which may require some effort to debug. - -### Remote Debugging on GitHub - -For remote debugging, you can monitor the status of your automation jobs in two ways: - -1. Create a pull request and view the CI status integration there. -2. Visit the [Actions tab of your repository](https://github.com/rl-institut/super-repository/actions) to see all available job executions. - -These options allow you to closely monitor the progress and outcomes of your CI workflow, ensuring the reliability and quality of your codebase. diff --git a/docs/development/documentation/index.md b/docs/development/documentation/index.md index a3499b7..6a448e9 100644 --- a/docs/development/documentation/index.md +++ b/docs/development/documentation/index.md @@ -2,18 +2,18 @@ ## README -The repository contains a `README.rst` file with basic information.
+The repository contains a πŸ“ `README.rst` file with basic information.
It gives a short introduction to the project and links to other relevant files. ## Changelog -The `CHANGELOG.md` is a record of all notable changes made to a project.
+The πŸ“ `CHANGELOG.md` is a record of all notable changes made to a project.
It is structured by each release and divided by additions, changes, and removals.
## MkDocs [MkDocs](https://www.mkdocs.org/) is a fast and simple static site generator that is used for documentation.
-The source files are written in [Markdown](https://www.markdownguide.org/cheat-sheet/), and configured with `mkdocs.yml`.
+The source files are written in [Markdown](https://www.markdownguide.org/cheat-sheet/), and configured with πŸ“ `mkdocs.yml`.
[Material theme](https://squidfunk.github.io/mkdocs-material/) enables additional features and an elegant design.
@@ -42,7 +42,7 @@ Publish documentation on **GitHub Pages**.
#### GitHub Action πŸ™ Deploy the documentation with **GitHub Actions**.
-The file `.github\workflows\documentation.yml` creates an automated GitHub workflow.
+The file πŸ“ `.github\workflows\documentation.yml` creates an automated GitHub workflow.
It is configured to be pushed to the branch `gh-page` and then deployed online.
A commit on the `develop` branch starts the workflow. @@ -51,11 +51,11 @@ A commit on the `develop` branch starts the workflow. The package [mike](https://github.com/jimporter/mike) is used to deploy [multiple versions](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/?h=versioning) of the documentation.
πŸ’» `pip install mike` install mike
πŸ’» `mike deploy --push --update-aliases 0.1 latest` deploys the latest version
-πŸ’» `mike set-default --push latest` Set the default version to latest +πŸ’» `mike set-default --push latest` Set the default version to latest
πŸ’» `mike deploy develop --push` deploys the develop branch !!! note "Mike Versions" - It is recommended to use only the **Minor Versions** (e.g. 0.1) and exclude the **Patch Version** (e.g. 0.1.1)! + It is recommended to use only the **Minor Versions** (for example 0.1) and exclude the **Patch Version** (for example 0.1.1)! Other useful commands are:
πŸ’» `mike serve` test mike on [`http://localhost:8000`](http://localhost:8000)
diff --git a/docs/development/release/index.md b/docs/development/release/index.md index 04c2aa7..5925b70 100644 --- a/docs/development/release/index.md +++ b/docs/development/release/index.md @@ -1,18 +1,11 @@ # Release -- RELEASE_PROCEDURE.md -- VERSION -- MANIFEST.in -- .bumpversion.cfg - -# Release Procedure - -The release has four goals: +The software release has four main goals: 1. Merge the new features to the `production` branch -2. Create a [GitHub Release](https://github.com/rl-institut/super-repo/releases) +2. Create a [GitHub Release](https://github.com/rl-institut/super-repository/releases) 3. Update the documentation 4. Publish a new version of the package at PyPI -The [RELEASE_PROCEDURE.md](https://github.com/rl-institut/super-repo/blob/production/RELEASE_PROCEDURE.md) +The [RELEASE_PROCEDURE.md](https://github.com/rl-institut/super-repository/blob/production/RELEASE_PROCEDURE.md) contain detailed instructions to do a release. diff --git a/docs/css/extra.css b/docs/extra.css similarity index 100% rename from docs/css/extra.css rename to docs/extra.css diff --git a/docs/code/code_example.md b/docs/user_documentation/code_example.md similarity index 100% rename from docs/code/code_example.md rename to docs/user_documentation/code_example.md diff --git a/docs/code/index.md b/docs/user_documentation/index.md similarity index 100% rename from docs/code/index.md rename to docs/user_documentation/index.md diff --git a/docs/code/install/index.md b/docs/user_documentation/install/index.md similarity index 100% rename from docs/code/install/index.md rename to docs/user_documentation/install/index.md diff --git a/mkdocs.yml b/mkdocs.yml index aca4e00..15ce9d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,7 +60,7 @@ extra: provider: mike extra_css: - - css/extra.css + - extra.css # Navigation nav: @@ -71,22 +71,21 @@ nav: - Collaboration: - development/collaboration/index.md - License and Citation: development/collaboration/license_and_citation.md + - Git: development/git/index.md - Users: development/collaboration/users.md - Chat: development/collaboration/chat.md - Meetings: development/collaboration/meeting.md - Code of Conduct: development/collaboration/code_of_conduct.md - - Git: - - development/git/index.md - - Continuous Integration: - - development/continuous-integration/index.md - - Code Style: - - code/style/index.md - + - Best Practices: + - Continuous Integration: development/best-practice/continuous-integration.md + - Test-Driven Development: development/best-practice/test_driven_development.md + - Pre-commit Hooks: development/best-practice/pre_commit_hooks.md + - Code Style: development/best-practice/code_style.md - Release: - development/release/index.md - - Code Documentation: + - User Documentation: - Install: - - code/install/index.md + - user_documentation/install/index.md - Functions: - - code/index.md - - code/code_example.md + - user_documentation/index.md + - user_documentation/code_example.md From 5ea9fa0d8c74745b3f71d8ad8dc04473b8b05e02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludwig=20H=C3=BClk?= Date: Fri, 6 Dec 2024 01:06:53 +0100 Subject: [PATCH 3/3] Update changelog #34 --- CHANGELOG.md | 1 + docs/development/best-practice/pre_commit_hooks.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ef6550..c8f39ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Update GitHub Action for develop branch [(#58)](https://github.com/rl-institut/super-repository/pull/58) - Update the sections and merge subpages of the documentation [(#62)](https://github.com/rl-institut/super-repository/pull/62) - Update documentation for release [(#69)](https://github.com/rl-institut/super-repository/pull/69) +- Update documentation best-practices [(#72)](https://github.com/rl-institut/super-repository/pull/72) ### Removed diff --git a/docs/development/best-practice/pre_commit_hooks.md b/docs/development/best-practice/pre_commit_hooks.md index 9dd560c..e0a1213 100644 --- a/docs/development/best-practice/pre_commit_hooks.md +++ b/docs/development/best-practice/pre_commit_hooks.md @@ -21,6 +21,5 @@ Now, every time you commit changes, the pre-commit hooks will automatically
run the checks defined in your configuration file, ensuring code quality before committing. - !!! note "Used Icons" πŸ™ GitHub | πŸ’  git | πŸ“ File | πŸ’» Command Line