Versioning

.github/workflows/_build_doc.yaml

@@ -13,7 +13,7 @@ on:
       py:
         type: string
         default: '3.11'
-      version_overwrite:
+      version_override:
         type: string
         default: ''
 
@@ -48,9 +48,9 @@ jobs:
             --requirement fairseq2n/python/requirements-build.txt\
             --requirement doc/requirements.txt
       - name: Overwrite project version
-        if: inputs.version_overwrite
+        if: inputs.version_override
         run: |
-          tools/set-project-version.sh ${{ inputs.version_overwrite }}
+          tools/set-project-version.sh ${{ inputs.version_override }}
       - name: Install fairseq2n
         run: |
           pip install --editable fairseq2n/python

.github/workflows/_build_wheel-linux.yaml

@@ -25,7 +25,7 @@ on:
       artifacts_name:
         type: string
         default: 'wheels'
-      version_overwrite:
+      version_override:
         type: string
         default: ''
       label_version_with_variant:
@@ -69,9 +69,9 @@ jobs:
         run: |
           pip install --requirement fairseq2n/python/requirements-build.txt
       - name: Override project version
-        if: inputs.version_overwrite
+        if: inputs.version_override
         run: |
-          tools/set-project-version.sh ${{ inputs.version_overwrite }}
+          tools/set-project-version.sh ${{ inputs.version_override }}
       - name: Set build variant as local version label
         if: inputs.label_version_with_variant
         env:
@@ -116,7 +116,6 @@ jobs:
             -GNinja\
             -DCMAKE_BUILD_TYPE=$build_type\
             -DCMAKE_CUDA_ARCHITECTURES=$cuda_archs\
-            -DFAIRSEQ2N_INSTALL_STANDALONE=ON\
             -DFAIRSEQ2N_PERFORM_LTO=$lto\
             -DFAIRSEQ2N_SANITIZERS="${SANITIZERS/_/;}"\
             -DFAIRSEQ2N_TREAT_WARNINGS_AS_ERRORS=ON\

.github/workflows/_build_wheel-macos.yaml

@@ -19,7 +19,7 @@ on:
       artifacts_name:
         type: string
         default: 'wheels'
-      version_overwrite:
+      version_override:
         type: string
         default: ''
 
@@ -50,17 +50,16 @@ jobs:
         run: |
           pip install --requirement fairseq2n/python/requirements-build.txt
       - name: Override project version
-        if: inputs.version_overwrite
+        if: inputs.version_override
         run: |
-          tools/set-project-version.sh ${{ inputs.version_overwrite }}
+          tools/set-project-version.sh ${{ inputs.version_override }}
       - name: Build fairseq2n
         working-directory: fairseq2n
         run: |
           cmake\
             -GNinja\
             -DCMAKE_BUILD_TYPE=Release\
             -DPython3_FIND_FRAMEWORK=NEVER\
-            -DFAIRSEQ2N_INSTALL_STANDALONE=ON\
             -DFAIRSEQ2N_PERFORM_LTO=OFF\
             -DFAIRSEQ2N_TREAT_WARNINGS_AS_ERRORS=ON\
             -DFAIRSEQ2N_THREAD_LIB=""\

.github/workflows/_build_wheels.yaml

@@ -10,7 +10,7 @@ on:
       release_type:
         type: string
         required: true
-      version_overwrite:
+      version_override:
         type: string
         required: true
 
@@ -30,7 +30,7 @@ jobs:
       py: ${{ matrix.py }}
       variant: ${{ matrix.variant }}
       sanitizers: ${{ matrix.sanitizers }}
-      version_overwrite: ${{ inputs.version_overwrite }}
+      version_override: ${{ inputs.version_override }}
 
   build_pt131_wheel-linux:
     name: Build wheels (pt${{ matrix.torch }}, py${{ matrix.py }}, linux-x86_64, ${{ matrix.variant }}, ${{ matrix.sanitizers }})
@@ -47,7 +47,7 @@ jobs:
       py: ${{ matrix.py }}
       variant: ${{ matrix.variant }}
       sanitizers: ${{ matrix.sanitizers }}
-      version_overwrite: ${{ inputs.version_overwrite }}
+      version_override: ${{ inputs.version_override }}
 
   build_pt20_wheel-linux:
     name: Build wheels (pt${{ matrix.torch }}, py${{ matrix.py }}, linux-x86_64, ${{ matrix.variant }}, ${{ matrix.sanitizers }})
@@ -80,7 +80,7 @@ jobs:
       py: ${{ matrix.py }}
       variant: ${{ matrix.variant }}
       sanitizers: ${{ matrix.sanitizers }}
-      version_overwrite: ${{ inputs.version_overwrite }}
+      version_override: ${{ inputs.version_override }}
       run_integration_tests: ${{ matrix.run_integration_tests }}
 
   build_pypi_wheel-linux:
@@ -98,7 +98,7 @@ jobs:
       py: ${{ matrix.py }}
       variant: ${{ matrix.variant }}
       artifacts_name: 'pypi'
-      version_overwrite: ${{ inputs.version_overwrite }}
+      version_override: ${{ inputs.version_override }}
       label_version_with_variant: false
 
 #  build_pypi_wheel-macos:
@@ -114,4 +114,4 @@ jobs:
 #      torch: ${{ matrix.torch }}
 #      py: ${{ matrix.py }}
 #      artifacts_name: 'pypi'
-#      version_overwrite: ${{ inputs.version_overwrite }}
+#      version_override: ${{ inputs.version_override }}

.github/workflows/_publish_doc.yaml

@@ -37,12 +37,12 @@ jobs:
             doc_dir=nightly
           else
             # Ignore pre-release segment for directory name.
-            mmp_version=$(echo $version | grep --only-matching --extended-regexp '^([0-9]+\.)*[0-9]+' -)
+            mmm_version=$(echo $version | grep --only-matching --extended-regexp '^([0-9]+\.)*[0-9]+' -)
 
-            doc_dir=$mmp_version
+            doc_dir=$mmm_version
 
             # If we have a stable release, update the 'stable' symlink.
-            if [[ $version == $mmp_version ]]; then
+            if [[ $version == $mmm_version ]]; then
                 ln --symbolic --no-target-directory --force $doc_dir stable
             fi
           fi

.github/workflows/ci_build_wheels.yaml

@@ -14,13 +14,6 @@ on:
       - 'doc/**'
 
 jobs:
-  test_py_devel:
-    name: Test Python development
-    uses: ./.github/workflows/_test_py_devel.yaml
-    with:
-      torch: '2.0.1'
-      py: '3.11'
-
   build_wheel-linux:
     name: Build wheels (pt${{ matrix.torch }}, py${{ matrix.py }}, linux-x86_64, ${{ matrix.variant }}, ${{ matrix.sanitizers }})
     uses: ./.github/workflows/_build_wheel-linux.yaml

.github/workflows/release.yaml

@@ -28,7 +28,7 @@ jobs:
   process_version:
     name: Process project version
     outputs:
-      version_overwrite: ${{ steps.stamp_version.outputs.version_overwrite }}
+      version_override: ${{ steps.stamp_version.outputs.version_override }}
     runs-on: ubuntu-latest
     steps:
       - name: Check-out the repository
@@ -40,8 +40,8 @@ jobs:
           version=$(cat VERSION)
 
           if [[ $RELEASE_TYPE != nightly ]]; then
-            if [[ $version == *+* ]]; then
-              echo "A PEP 440 version with a local label cannot be released as '$RELEASE_TYPE'." >&2
+            if [[ $version == *.dev* ]]; then
+              echo "A PEP 440 version with dev segment cannot be released as '$RELEASE_TYPE'." >&2
 
               exit 1
             fi
@@ -52,8 +52,8 @@ jobs:
         run: |
           version=$(cat VERSION)
 
-          # Remove local version label and append date-stamped dev segment.
-          echo version_overwrite=${version%+*}.dev$(date +%Y%m%d) >> "$GITHUB_OUTPUT"
+          # Append date-stamped dev segment.
+          echo version_override=${version%.dev*}.dev$(date +%Y%m%d) >> "$GITHUB_OUTPUT"
 
   lint:
     name: Lint
@@ -65,14 +65,14 @@ jobs:
     uses: ./.github/workflows/_build_wheels.yaml
     with:
       release_type: ${{ inputs.release_type }}
-      version_overwrite: ${{ needs.process_version.outputs.version_overwrite }}
+      version_override: ${{ needs.process_version.outputs.version_override }}
 
   build_doc:
     name: Build documentation
     needs: [process_version]
     uses: ./.github/workflows/_build_doc.yaml
     with:
-      version_overwrite: ${{ needs.process_version.outputs.version_overwrite }}
+      version_override: ${{ needs.process_version.outputs.version_override }}
 
   publish:
     name: Publish

CONTRIBUTING.md

@@ -1,29 +1,43 @@
 # Contributing to fairseq2
-We want to make contributing to fairseq2 as easy and transparent as possible.
-Please make sure to read this guideline carefully.
+We want to make contributing to fairseq2 as easy as possible. Please make sure
+to read this guideline carefully.
 
 
 ## Setting up Development Environment
 fairseq2 consists of two packages; the user-facing fairseq2 package implemented
 in pure Python, and the fairseq2n package that contains the C++ and CUDA
-portions of the library. If fairseq2n is available as a pre-built package for
-your system (check installation instructions for your operating system in
-[README](.)), and if you are interested in only modifying Python portions of
-fairseq2, you can use an editable pip installation as described below.
-Otherwise, if you are planning to work on C++ or CUDA, or if fairseq2n is not
-available as a pre-built package for your system, please follow the install
-instructions [here](INSTALL_FROM_SOURCE.md).
+portions of the library. If pre-built fairseq2n nightly packages are available
+for your system (check [README](.#nightlies)), and if you are interested in only
+modifying Python portions of fairseq2, you can use an editable pip installation
+as described below. Otherwise, if you are planning to work on C++ or CUDA, or if
+fairseq2n is not available as a pre-built package for your system, please follow
+the installation instructions [here](INSTALL_FROM_SOURCE.md).
 
-For an editable installation, first, clone the fairseq2 repository to your
-machine:
+For an editable installation, first, install a nightly build of fairseq2n (shown
+for PyTorch `2.0.1` and variant `cu118`):
+
+```sh
+pip install fairseq2n\
+  --pre --upgrade --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.0.1/cu118
+```
+
+> [!WARNING]
+> fairseq2n relies on the C++ API of PyTorch which has no API/ABI compatibility
+> between releases. This means **you have to install the fairseq2n variant that
+> exactly matches your PyTorch version**. Otherwise, you might experience issues
+> like immediate process crashes or spurious segfaults. For the same reason, if
+> you upgrade your PyTorch version, you must also upgrade your fairseq2n
+> installation.
+
+Then, clone the fairseq2 repository to your machine:
 
 ```sh
 git clone https://github.com/facebookresearch/fairseq2.git
 
 cd fairseq2
 ```
 
-Then, install the fairseq2 package in editable mode:
+And, install the fairseq2 package in editable mode:
 
 ```sh
 pip install -e .
@@ -36,6 +50,12 @@ formatters):
 pip install -r requirements-devel.txt
 ```
 
+> [!NOTE]
+> Any time you pull the latest fairseq2 commits from GitHub, make sure to re-run
+> the fairseq2n installation command above to get the most up-to-date binary. If
+> you observe runtime or test failures after the installation, it might be
+> because the latest nightlies are not published yet. If the problem persists
+> after about 12 hours, please create a GitHub issue.
 
 ## Testing Your Work