Skip to content

Commit

Permalink
Merge pull request #557 from aai-institute/doc/version-added-document…
Browse files Browse the repository at this point in the history
…ation

Add section to contributing guide about adding notes for new features…
  • Loading branch information
AnesBenmerzoug authored Apr 8, 2024
2 parents 04076cd + 49bfa1d commit de606cd
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 0 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
[PR #543](https://github.com/aai-institute/pyDVL/pull/543)
- Glossary of data valuation and influence terms in the documentation
[PR #537](https://github.com/aai-institute/pyDVL/pull/537
- Documentation about writing notes for new features, changes or deprecations.
[PR #557](https://github.com/aai-institute/pyDVL/pull/557)

### Fixed

Expand Down
52 changes: 52 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,58 @@ that a link will remain valid, add a custom anchor to the section title:
(note the space after the opening brace). You can then refer to it within
another markdown file with `[Some section][permanent-anchor-to-some-section]`.

### Adding notes about new features, changes or deprecations

We use the admonition extension of
[Mkdocs Material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
to create admonitions, also known as call-outs, that hold information
about when a certain feature was added, changed or deprecated and optionally
a description with more details. We put the admonition directly
in a module's, a function's or class' docstring.

We use the following syntax:

```
!!! tip "<Event Type> in version <Version Number>"
<Optional Description>
```

The description is useful when the note is about a smaller change
such as a parameter.

- For a new feature, we use:

```
!!! tip "New in version <Version Number>"
<Optional Description>
```

- For a change to an existing feature we use:

```
!!! tip "Changed in version <Version Number>"
<Optional Description>
```

For example, for a change in version `1.2.3` that adds kwargs
to a class' constructor we would write:

```
!!! tip "Changed in version 1.2.3"
Added kwargs to the constructor.
```

- For a deprecation we use:

```
!!! tip "Deprecated in version <Version Number>"
<Optional Description>
```

### Using bibliography

Expand Down

0 comments on commit de606cd

Please sign in to comment.