(機械翻訳) ピラミッドのアップグレード

新しいバージョンのPyramidがリリースされると、機能が廃止されたり、古いリリースで廃止された機能が削除されることがあります。フィーチャーがPyramidから削除されると、それらのフィーチャーに依存するアプリケーションが中断し始めます。この章では、使用しているPyramidのバージョンをアップグレードするときにPyramidアプリケーションが動作し続けるようにする方法について説明します。

リリース番号について

従来、Pythonでのアプリケーションのバージョン番号は `` major.minor.micro``と記述されていました。 Pyramidのバージョンが"1.2.3 "であれば、メジャーバージョン"1 "、マイナーバージョン"2 "、マイクロバージョン"3 "のピラミッドバージョンを実行していることを意味します。 。 "メジャー"リリースとは、最初のドット番号をインクリメントするものです。 2.XXは1.XXに従うかもしれません。"マイナー"リリースは、第2のドット番号をインクリメントするものです。 1.3.Xは1.2.Xに続く可能性があります。 "マイクロ"リリースは、3番目のドット番号をインクリメントするものです。 1.2.3は1.2.2に続くかもしれない。一般に、マイクロリリースは「バグ修正のみ」で新機能は含まれていません。マイナーリリースには新機能が含まれていますが、旧バージョンとの下位互換性があります。メジャーリリースでは大きな互換性がありません。

ピラミッドのコアチームは、機能を削除する際には控えめです。不必要に機能を削除するわけではありませんが、私たちは人間であり、いくつかの機能を進化的なデッドエンドにする間違いを犯します。デッドエンド機能をある程度サポートしていますが、Pyramidの各機能は特定の文書化とメンテナンスの負担を抱いているため、それらをサポートするコストよりもコストを削減する必要があります。

廃止と削除のポリシー

機能がPyramidまたはその公式のアドオンから削除される予定の場合、コア開発チームは次の手順を実行します。

  • この機能を使用すると、その機能が非難されたバージョンを示す `DeprecationWarning`が生成され始めます。
  • その機能が推奨されていないことを示すメモが文書に追加されます。
  • 非推奨について：ref： `changelog`にメモが追加されています。

廃止予定の機能が最終的に削除されると、

  • この機能は削除されました。
  • 削除について：ref： `changelog`にメモが追加されています。

Features are never removed in micro releases. They are only removed in minor and major releases. Deprecated features are kept around for at least three minor releases from the time the feature became deprecated. Therefore, if a feature is added in Pyramid 1.0, but it's deprecated in Pyramid 1.1, it will be kept around through all 1.1.X releases, all 1.2.X releases and all 1.3.X releases. It will finally be removed in the first 1.4.X release.

フィーチャは、正式に廃止されるのではなく、"docs-deprecated "です。これは、その機能が無期限に保持されることを意味しますが、その機能は文書から削除されるか、または他の新しい機能を使用するように伝える文書に追加されます。これは、古い機能を維持するコストが非常に低く、サポートとドキュメントの負担が非常に少ないときに発生します。たとえば、受け入れる引数を変更せずにAPIである関数の名前を変更することができます。この場合、関数の名前を変更し、新しい関数名を指すようにドキュメントを変更しますが、古い関数名への下位互換性のある別名を残して、古いコードが壊れないようにします。

"Docs deprecated "機能は"forever "で動作する傾向があります。つまり、削除されず、廃止予定の警告が生成されることはありません。しかし、そのような変更は：ref： `changelog`に書かれているので、あなたのコードを読んでいる人がPyramidのドキュメントで使用しているAPIを見つけることができるように古いスペルを新しいものに変更する必要があることを知ることは可能です。

Pythonサポートポリシー

Pyramidのバージョンリリース時には、Pythonのすべてのバージョンがライフスパンの終わりまでサポートされています。特定のバージョンのPythonの廃止は、セキュリティアップデートがリリースされなくなったときです。

Pyramidの特定のリリースのPythonサポートを確認するには、リポジトリのバージョンのルートにある `` tox.ini``ファイルを参照してください。

変更履歴に相談する

最新のPyramidリリースへのアップグレードによるアプリケーションの失敗に対する最初の防衛線は、常に：ref： `changelog`を読んで、現在実行しているリリースと現在実行しているリリースの間の各リリースの廃止と削除を見つけますアップグレードしたい変更履歴は、「非推奨」セクション内のすべての非推奨と、各リリース用の「後方互換性のない」セクション内のすべての削除を記録します。

変更履歴には、コードを変更して廃止予定の警告を回避する方法や、廃止予定のスペルを新しいものに変更する方法が含まれることがよくあります。変更履歴の各非推奨説明に従って、アプリケーションにgrepやその他のコード検索を行い、変更ログの例を使用して潜在的な問題を修正することができます。

新しいPyramidリリースでアプリケーションをテストする

アプリケーションを新しいPyramidリリースにアップグレードし、変更履歴ノートを使用してできるだけ修正を加えたら、アプリケーションのテストを実行したいと思うでしょう（ref： `running_tests`を参照）。テスト実行時にDeprecationWarningsがコンソールに表示されることがわかります。

$ python -Wd setup.py test -q

`` -Wd``引数はPythonに、廃止予定の警告をコンソールに表示するように指示します。 `Python -Wフラグのドキュメント<https://docs.python.org/2/using/cmdline.html#cmdoption-W>詳細は_を参照してください。

テストが実行されると、廃止予定を説明するコンソールに廃止予定の警告が出力され、廃止予定の警告が表示されないようにする方法が示されます。例えば：

$ python -Wd setup.py test -q
# .. elided ...
running build_ext
/home/chrism/projects/pyramid/env27/myproj/myproj/views.py:3:
DeprecationWarning: static: The "pyramid.view.static" class is deprecated
as of Pyramid 1.1; use the "pyramid.static.static_view" class instead with
the "use_subpath" argument set to True.
  from pyramid.view import static
.
----------------------------------------------------------------------
Ran 1 test in 0.014s

OK

上記の場合、問題を引き起こしている `` myproj.views``モジュール（ `` from pyramid.view import static``）の3行目です：

1
2
3
4
from pyramid.view import view_config

from pyramid.view import static
myview = static('static', 'static')

廃止予定の警告は私にそれを修正する方法を教えているので、コードを変更してより新しい方法で行うことができます：

1
2
3
4
from pyramid.view import view_config

from pyramid.static import static_view
myview = static_view('static', 'static', use_subpath=True)

テストをもう一度実行すると、廃止予定の警告がコンソールに表示されなくなります。

$ python -Wd setup.py test -q
# .. elided ...
running build_ext
.
----------------------------------------------------------------------
Ran 1 test in 0.014s

OK

私のアプリケーションにはテストがありません。

あなたのアプリケーションにテストがない場合、または適度なテストカバレッジしかない場合は、テストの実行はあまり意味しません。なぜなら、非推奨警告を生成するピラミッドコードパスは実行されないからです。

この状況では、 `` PYTHONWARNINGS``環境変数が `` default``に設定された状態で、サーバを起動してアプリケーションを対話的に起動することができます。 UNIXでは、次の方法でこれを行うことができます。

$ PYTHONWARNINGS=default $VENV/bin/pserve development.ini

Windowsでは、次の2つのコマンドを発行する必要があります。

c:\> set PYTHONWARNINGS=default
c:\> Scripts\pserve development.ini

この時点では、コードパスが生成されるたびに非推奨警告がコンソールに出力されることが保証されています。対話的にアプリケーションをクリックして生成することができます：ref： `testing_under_new_release`で説明されているように修正してください。

PYTHONWARNINGS環境変数のドキュメント<https://docs.python.org/2/using/cmdline.html#envvar-PYTHONWARNINGS> `_または Python -Wフラグのドキュメント<https://docs.python.org/2/using/cmdline.html#cmdoption-W>詳細は_を参照してください。

最新のPyramidリリースへのアップグレード

アプリケーションを最新のPyramidリリースにアップグレードする場合は、最新のマイナーリリースを段階的にアップグレードしてから、アプリケーションが現在実行しているものから最新のリリースで終了するものまで、アップグレードすることをお勧めします。たとえば、アプリケーションがPyramid 1.2.1で本番環境で動作していて、最新のPyramid 1.3リリースがPyramid 1.3.3で、最新のPyramidリリースが1.4.4の場合は、これを行うことをお勧めします。

  • 最新の1.2リリースに環境をアップグレードしてください。たとえば、最新の1.2リリースは1.2.3かもしれないので、アップグレードしてください。次に、：ref： `testing_under_new_release`で説明されているように、アプリケーションのテストを1.2.3で実行します。廃止予定の警告と修正を書き留めておいてください。
  • 最新の1.3リリース1.3.3にアップグレードしてください。アプリケーションのテストを実行し、廃止予定の警告を書き留め、修復します。
  • 1.4.4にアップグレードしてください。アプリケーションのテストを実行し、廃止予定の警告を書き留め、修復します。

各マイナーリリースでアプリケーションのテストをスキップした場合（たとえば、1.2.1から1.4.4に直接アップグレードする場合）、廃止予定の警告が表示されず、機能の削除によって発生したエラーを特定するのに時間がかかることがありますマイナーリリースごとに段階的にアップグレードすることになります。