Table Of Contents

Contents

  1. Home
  2. For Developers
  3. Project Lead Tasks

Project Lead Tasks

This document provides details common project lead tasks, and, as creating a release is a big part of that, there is some overlap with the summary document Source Code release cycle.

Development Environment

An up to date ONIE DUE container should be used for Project Lead tasks. In addition to providing an environment with all needed tools, it assures that users building ONIE will be using exactly the same environment as the Project Lead, making it easier to track down build issues, and reducing support efforts as everyone can have a known working build environment.

Pull Requests

  1. Consider using the onie-pr script to automatically pull in a pull request number from GitHub. This script has its dependencies satisfied in a DUE ONIE build container.

  2. Examine the scope of the commit. Changes limited to the product under the ./machine directory are considered to be how the manufacturer wants things to work, and as those changes will only affect them, there are usually no issues pulling in that code. However, if the changes touch code used in the build of other ONIE targets that may affect all platforms and thus requires a closer look and testing on the x86 and arm64 virtual targets (as well as hardware, if available).

  3. If minor changes are required for a pull request, consider doing them yourself rather than pushing the request back.

  4. If major changes are required, respond to the submitter in the pull request.

  5. Build the platform for the all and demo targets. If it builds clean, use git –amend to update commit message to make sure it is descriptive and formatted cleanly. Grammatical clean up for clarity can be done as needed. Most programmers aren’t English majors.

  6. Testing. The reality is that the Project Lead will not have access to every platform. So if the pull request builds cleanly, it should be accepted. Again, if the commit affects core ONIE functionality, the x86 and ARM64 virtual machines should be used for testing. This will also provide the submitter the ability to replicate any issues the Project Lead sees, in order to resolve the issues.

  7. If a new platform was not added to the onie/build-config/scripts/onie-build-targets.json file, or a platform has been successfully tested with a new release, make sure there is an up to date entry there for it.

  8. Make sure the syntax of the json file has not been corrupted by parsing the json file with:

cat onie-build-targets.json | jq '.'

This should print out all fields if there are no syntax errors.

  1. If it all looks good, push the commit

  2. Go to the pull request on GitHub and close it out with a thank you for the commit.

Making a release

Releases are a two step process

  1. Create a release candidate the month before the release: months 1,4,7,10 or January, April, July, October

  2. Create the quarterly release in February, May, August, and November, or months 2,5,8,11.

Note that the official quarterly release is mostly a copy of the last release candidate with the “release candidate” references removed, so save your work.

Creating release notes

The candidate release note will be named with an -rcX For example:

2019.08-rc1.txt

While the official release will be named:

2019.08.txt

The contents of the two files will be identical except for the ‘rc’ in the text if nothing has changed in the month between publishing the release candidate, and publishing the release.

Start with the changelog diff from last release: Example:

git log --oneline 2022.02..HEAD

Then put changes (new platforms, bug fixes, etc, in the appropriate areas.) The entries don’t have to exactly match the commits, but should read clearly. If a new entry had subsequent updates (adding a README file, for example) that should just be considered to be part of the submission.

Release notes should have the following format, as shown in the release email that gets sent (a later step) https://ocp-all.groups.io/g/OCP-ONIE/message/255

The Git statistics are generated by using onie/contrib/git-stats/onie-git-stats to log differences between the last release and the HEAD Example:: onie/contrib/git-stats/onie-git-stats 2022.02..HEAD quarterly

Creating the release candidate

Use the create-release script to publish a release:

onie/build-config/scripts/create-release $version $release_notes

Example:

onie/build-config/scripts/create-release 2022.08-rc1 ./<pathto>/2022.08-rc1.txt
And it should be available at

https://github.com/opencomputeproject/onie

Release debugging

Tip: You can test the create-release script on a private GitHub fork as the script will push to your fork. If the branch/tag goes bad before push clean up locally with something like:

git tag -d 2022.05-rc1
git branch -D 2022.05-rc1br

Email everyone

Send an update to the ONIE mailing list to let everyone know about the release candidate. OCP-ONIE@OCP-All.groups.io

This should show up in the mailing list archives shortly: https://ocp-all.groups.io/g/OCP-ONIE/topics

Creating the REAL quarterly release

This is pretty much a copy of the release candidate steps with the “candidate” references removed, and the ONIE documentation gets updated.

Again, run this from inside a Debian 10 DUE container, as it will have the build environment and all of the documentation update tools.

Get a clean checkout of master

Update the release notes as needed. This may be just as simple as renaming the “rc.txt” release notes for the release candidate and editing them to not have an rc suffix referenced.

Publish the release

This is mostly the release candidate, except without the “-rc” references

onie/build-config/scripts/create-release $version $release_notes

Example

./build-config/scripts/create-release 2022.08 ~/release-notes/2022.08.txt

Send the release email

Again, pretty much the same as the release candidate mail:

See the example here: https://ocp-all.groups.io/g/OCP-ONIE/message/248

Get the short link from here (two overlapping loops on the upper right side of the page), since that will be required to update the documentation. https://ocp-all.groups.io/g/OCP-ONIE/topics The link should look like:

https://ocp-all.groups.io/g/OCP-ONIE/message/248

Update and publish the documentation

This step only happens with the official quarterly release.

1 - Check out the docs branch of ONIE

  1. cd onie

  2. git checkout docs

    Note - if you get detached head errors here, you’ve probably got an existing directory. Nuking it a and a clean checkout handles this. Look for a more elegant solution next time.

    Also note that the directory looks a lot different in docs. This is because the documentation consists of .rst files that get compiled to html and are stored in a gh-pages branch before being pushed to the web site as part of publish.

Sphinx is used to generate the documentation, and it comes in the ONIE DUE container. If you use a different version of Sphinx, expect a lot of file changes.

2 - Edit files

Update the following, adding the link to the release email from above where needed. Most of this should be just cut,paste, edit the date and the link, and adding a summary of changes. Follow the formatting from the last release.

  1. ./docs/news/index.rst and use that OCP-ONIE link you copied to reference your release message. Ideally you’ll just have to copy, paste, edit the number in the link, and add a line about the release.

  2. ./docs/index.rst , which is the home page, to have the same message for ‘what’s new’

  3. ./docs/developers/release.rst. While it should already have been updated with the current release as part of the commit, you can update the ‘Future Releases’ section to aim for the third Wednesday of the month next year.

So that’s a total of 3 files that always update for a release.

  1. If needed, update any other .rst files if there is any new documentation, but this happens infrequently.

3 - Build the documents

  1. cd to top level onie directory

  2. make docs

    You should see a message about getting upstream Guzzle Sphinx theme, and it should end with the location of the generated html under ./build

  3. Make sure things aren’t radically different. Note that you should only see about 3 files modified here.

Example:

modified:   docs/developers/release.rst
modified:   docs/index.rst
modified:   docs/news/index.rst

A slew of changes indicates a problem OR a new version of Sphinx. If you upgraded Sphinx, then that’s fine. Otherwise, panic.

5 - Commit the changes to the docs branch

  1. Git commit the change to the docs branch with an appropriate message, and a Signed-off-by

    Example:

    Updated home page news for 2020.11 release.
Signed-off-by: Alex Doyle <adoyle@nvidia.com>

  2. git push

6 - Update the website html

Now the base docs branch is updated, time to do the html:

  1. make publish

    This generates html off the docs code committed in step 8 above, and the html code will need to be pushed. Make sure things look sane. If you see a ton of files and deletions, you’ve probably got the wrong version of Sphinx.

A probably sane example:

modified:   _sources/developers/release.rst.txt
      modified:   _sources/index.rst.txt
      modified:   _sources/news/index.rst.txt
      modified:   developers/release.html
      modified:   index.html
      modified:   news/index.html
      modified:   objects.inv
      modified:   searchindex.js

NOTE: going to the Debian 9 container used a 1.7.9 version of Sphinx vs the 1.6.7 in Ubuntu 18 (used for the last few releases as the 1.2.? on marvel-07 failed hard.) This caused a number of files to be generated differently and added a new one - what should have been the 4 files changed was closer to 30. I had to cd to /tmp/onie-docs and add a new file to the commit in the gh-pages branch. This was manually doing the steps in onie/scripts/publish-docs

…And you’re done

Source Code Release Cycle
Command Line Reference
© Copyright 2013-2018, Cumulus Networks, Inc. All Rights Reserved.