Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update contributing guidelines to discuss versioning #355

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

update contributing guidelines to discuss versioning #355

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 49 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,12 @@ to easily generate documentation from markdown.
### Installing Dependencies

```bash
sydo apt-get update
sudo apt-get update
sudo apt-get -y install python3-pip
sudo apt-get -y install mkdocs
pip3 install mkdocs-material mike
```


### Testing

To quickly test the version of the documentation you're using, without commiting
Expand Down Expand Up @@ -81,9 +80,52 @@ Finally, we add the file to our navigation in ``mkdocs.yml``
Now, when you build the documentation you should see the page that
we've added in the "Reference" section with the title "Maintainers".

### Updating the Changelog
## Contributing a change

All changes to JetBot are made through pull requests on GitHub. These pull requests should be made directly
to the master branch. The procedure, in general, is as follows

### Keep it minimal

Try to make the scope of a change as small as possible while still accomplishing something valuable. Changes that accomplish more than one thing at a time are more difficult to validate. There could be an amazing contribution in a large pull request, but if it's associated with many other unrelated changes, it's very difficult to integrate safely. If it's short and sweet, we're better able to assess the purpose and impact of the change and integrate quickly.
If theres more you want to contribute, simply create multiple pull requests :).

### Update the changelog

If a change is worth other developers and users knowing about, it should include an entry in the ``CHANGELOG.md`` file. For this, we follow the guidance of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) for
best practices in maintaining a chronological human-readable CHANGELOG.md file. Because *all* changes are directly made to master, this entry should *always and only* come under the *Master* section.

## Versioning

> This section is not relevant for most developers, but included for reference.

NVIDIA is responsible for versioning of the JetBot software. However, if you feel the state of the software is in a position that you might want to back reference, a version increment may be necessary. The general procedure we follow for versioning is as follows

1. A new version name is decided. This depends on the scope of changes since the previous version
2. The CHANGELOG is updated. A new section for the new version is created. Items in the master section are moved under this section. No new changes should be added in the versioning process, the content should merely be shifted.
3. The setup.py is updated to reflect the new version.
4. A pull request is made for the new version. The changes are squashed so the version increment happens atomically.
5. The commit is tagged with the version number.

Please note, versioning is related to the state of the JetBot repository. It occurs *independently* from SD card and docker container generation.

## SD Cards and Containers

> This section is not relevant for most developers, but included for reference.

When deemed necessary, new JetBot SD card images and/or docker containers may be released. All publicly released SD card images and containers are based on an existing state of software. These images and containers depend on more than just the version of JetBot software, such as system configuration and operating system versions. That said, they will always depend on JetBot software in some way, and it is important to note the version of software used.

1. The JetBot git commit hash
2. The JetBot version tag associated with a git hash

For public releases (2) is preferred. Though in some instances, a release tag may not be associated, such as if we want to release an experimental SD card image based on master. In this instance, the commit hash is used. In some instances, it may be possible that multiple SD cards exist for the same JetBot version, for example if they are configured for a specific system (ie: Jetson 2GB vs 4GB, JetPack 4.3 vs 4.4, etc.). The relevant information should be appended to the SD card name.

In summary,

```
jetbot-<jetbot commit hash or version>-<other information>
```

This file may be shared in multiple ways. Typically, this is through the JetBot documentation.

We follow the guidance of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) for
best practices in maintaining a chronological human-readable CHANGELOG.md file. If
the change is worth developers and users knowing about, consider adding an entry
to the change log.
> Please note, because SD card images, docker containers depend on the state of the JetBot software, references to these are not included before the git version tag, since this would create a circular dependency. Consider SD card images, docker containers, and documentation as separate projects, which *depend* on JetBot software.