From 5b525e97970b1b9706b4415de79abfe33e5955fc Mon Sep 17 00:00:00 2001 From: David Lord Date: Sun, 5 Jan 2025 09:01:49 -0800 Subject: [PATCH 1/2] markdown formatting (cherry picked from commit 6b361ce06b08454329286214072139228e8c2f33) --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index df4d41cb..a8fcdeec 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Flask -Flask is a lightweight [WSGI][] web application framework. It is designed +Flask is a lightweight [WSGI] web application framework. It is designed to make getting started quick and easy, with the ability to scale up to -complex applications. It began as a simple wrapper around [Werkzeug][] -and [Jinja][], and has become one of the most popular Python web +complex applications. It began as a simple wrapper around [Werkzeug] +and [Jinja], and has become one of the most popular Python web application frameworks. Flask offers suggestions, but doesn't enforce any dependencies or @@ -15,7 +15,6 @@ community that make adding new functionality easy. [Werkzeug]: https://werkzeug.palletsprojects.com/ [Jinja]: https://jinja.palletsprojects.com/ - ## A Simple Example ```python @@ -34,12 +33,11 @@ $ flask run * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) ``` - ## Donate The Pallets organization develops and supports Flask and the libraries it uses. In order to grow the community of contributors and users, and allow the maintainers to devote more time to the projects, [please -donate today][]. +donate today]. [please donate today]: https://palletsprojects.com/donate From 959052fb8d49c4473f6d8a928d745ae7c38c7e95 Mon Sep 17 00:00:00 2001 From: David Lord Date: Sun, 5 Jan 2025 09:02:41 -0800 Subject: [PATCH 2/2] use global contributing guide Remove the per-project files so we don't have to keep them in sync. GitHub's UI links to everything except the contributing guide, so add a section about that to the readme. (cherry picked from commit 60a11a730e8aa2450115385798ab8710804c6409) --- .github/ISSUE_TEMPLATE/config.yml | 4 +- CODE_OF_CONDUCT.md | 76 ---------- CONTRIBUTING.rst | 238 ------------------------------ README.md | 8 + docs/contributing.rst | 9 +- 5 files changed, 18 insertions(+), 317 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.rst diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3f27ac95..a8f9f0b7 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -3,9 +3,9 @@ contact_links: - name: Security issue url: https://github.com/pallets/flask/security/advisories/new about: Do not report security issues publicly. Create a private advisory. - - name: Questions + - name: Questions on GitHub Discussions url: https://github.com/pallets/flask/discussions/ about: Ask questions about your own code on the Discussions tab. - - name: Questions on + - name: Questions on Discord url: https://discord.gg/pallets about: Ask questions about your own code on our Discord chat. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index f4ba197d..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,76 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, nationality, personal -appearance, race, religion, or sexual identity and orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at report@palletsprojects.com. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see -https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index fed44978..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,238 +0,0 @@ -How to contribute to Flask -========================== - -Thank you for considering contributing to Flask! - - -Support questions ------------------ - -Please don't use the issue tracker for this. The issue tracker is a tool -to address bugs and feature requests in Flask itself. Use one of the -following resources for questions about using Flask or issues with your -own code: - -- The ``#questions`` channel on our Discord chat: - https://discord.gg/pallets -- Ask on `Stack Overflow`_. Search with Google first using: - ``site:stackoverflow.com flask {search term, exception message, etc.}`` -- Ask on our `GitHub Discussions`_ for long term discussion or larger - questions. - -.. _Stack Overflow: https://stackoverflow.com/questions/tagged/flask?tab=Frequent -.. _GitHub Discussions: https://github.com/pallets/flask/discussions - - -Reporting issues ----------------- - -Include the following information in your post: - -- Describe what you expected to happen. -- If possible, include a `minimal reproducible example`_ to help us - identify the issue. This also helps check that the issue is not with - your own code. -- Describe what actually happened. Include the full traceback if there - was an exception. -- List your Python and Flask versions. If possible, check if this - issue is already fixed in the latest releases or the latest code in - the repository. - -.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example - - -Submitting patches ------------------- - -If there is not an open issue for what you want to submit, prefer -opening one for discussion before working on a PR. You can work on any -issue that doesn't have an open PR linked to it or a maintainer assigned -to it. These show up in the sidebar. No need to ask if you can work on -an issue that interests you. - -Include the following in your patch: - -- Use `Black`_ to format your code. This and other tools will run - automatically if you install `pre-commit`_ using the instructions - below. -- Include tests if your patch adds or changes code. Make sure the test - fails without your patch. -- Update any relevant docs pages and docstrings. Docs pages and - docstrings should be wrapped at 72 characters. -- Add an entry in ``CHANGES.rst``. Use the same style as other - entries. Also include ``.. versionchanged::`` inline changelogs in - relevant docstrings. - -.. _Black: https://black.readthedocs.io -.. _pre-commit: https://pre-commit.com - - -First time setup using GitHub Codespaces -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -`GitHub Codespaces`_ creates a development environment that is already set up for the -project. By default it opens in Visual Studio Code for the Web, but this can -be changed in your GitHub profile settings to use Visual Studio Code or JetBrains -PyCharm on your local computer. - -- Make sure you have a `GitHub account`_. -- From the project's repository page, click the green "Code" button and then "Create - codespace on main". -- The codespace will be set up, then Visual Studio Code will open. However, you'll - need to wait a bit longer for the Python extension to be installed. You'll know it's - ready when the terminal at the bottom shows that the virtualenv was activated. -- Check out a branch and `start coding`_. - -.. _GitHub Codespaces: https://docs.github.com/en/codespaces -.. _devcontainer: https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers - -First time setup in your local environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Make sure you have a `GitHub account`_. -- Download and install the `latest version of git`_. -- Configure git with your `username`_ and `email`_. - - .. code-block:: text - - $ git config --global user.name 'your name' - $ git config --global user.email 'your email' - -- Fork Flask to your GitHub account by clicking the `Fork`_ button. -- `Clone`_ your fork locally, replacing ``your-username`` in the command below with - your actual username. - - .. code-block:: text - - $ git clone https://github.com/your-username/flask - $ cd flask - -- Create a virtualenv. Use the latest version of Python. - - - Linux/macOS - - .. code-block:: text - - $ python3 -m venv .venv - $ . .venv/bin/activate - - - Windows - - .. code-block:: text - - > py -3 -m venv .venv - > .venv\Scripts\activate - -- Install the development dependencies, then install Flask in editable mode. - - .. code-block:: text - - $ python -m pip install -U pip - $ pip install -r requirements/dev.txt && pip install -e . - -- Install the pre-commit hooks. - - .. code-block:: text - - $ pre-commit install --install-hooks - -.. _GitHub account: https://github.com/join -.. _latest version of git: https://git-scm.com/downloads -.. _username: https://docs.github.com/en/github/using-git/setting-your-username-in-git -.. _email: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address -.. _Fork: https://github.com/pallets/flask/fork -.. _Clone: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork - -.. _start coding: - -Start coding -~~~~~~~~~~~~ - -- Create a branch to identify the issue you would like to work on. If you're - submitting a bug or documentation fix, branch off of the latest ".x" branch. - - .. code-block:: text - - $ git fetch origin - $ git checkout -b your-branch-name origin/2.0.x - - If you're submitting a feature addition or change, branch off of the "main" branch. - - .. code-block:: text - - $ git fetch origin - $ git checkout -b your-branch-name origin/main - -- Using your favorite editor, make your changes, `committing as you go`_. - - - If you are in a codespace, you will be prompted to `create a fork`_ the first - time you make a commit. Enter ``Y`` to continue. - -- Include tests that cover any code changes you make. Make sure the test fails without - your patch. Run the tests as described below. -- Push your commits to your fork on GitHub and `create a pull request`_. Link to the - issue being addressed with ``fixes #123`` in the pull request description. - - .. code-block:: text - - $ git push --set-upstream origin your-branch-name - -.. _committing as you go: https://afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes -.. _create a fork: https://docs.github.com/en/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#about-automatic-forking -.. _create a pull request: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request - -.. _Running the tests: - -Running the tests -~~~~~~~~~~~~~~~~~ - -Run the basic test suite with pytest. - -.. code-block:: text - - $ pytest - -This runs the tests for the current environment, which is usually -sufficient. CI will run the full suite when you submit your pull -request. You can run the full test suite with tox if you don't want to -wait. - -.. code-block:: text - - $ tox - - -Running test coverage -~~~~~~~~~~~~~~~~~~~~~ - -Generating a report of lines that do not have test coverage can indicate -where to start contributing. Run ``pytest`` using ``coverage`` and -generate a report. - -If you are using GitHub Codespaces, ``coverage`` is already installed -so you can skip the installation command. - -.. code-block:: text - - $ pip install coverage - $ coverage run -m pytest - $ coverage html - -Open ``htmlcov/index.html`` in your browser to explore the report. - -Read more about `coverage `__. - - -Building the docs -~~~~~~~~~~~~~~~~~ - -Build the docs in the ``docs`` directory using Sphinx. - -.. code-block:: text - - $ cd docs - $ make html - -Open ``_build/html/index.html`` in your browser to view the docs. - -Read more about `Sphinx `__. diff --git a/README.md b/README.md index a8fcdeec..29312c65 100644 --- a/README.md +++ b/README.md @@ -41,3 +41,11 @@ allow the maintainers to devote more time to the projects, [please donate today]. [please donate today]: https://palletsprojects.com/donate + +## Contributing + +See our [detailed contributing documentation][contrib] for many ways to +contribute, including reporting issues, requesting features, asking or answering +questions, and making PRs. + +[contrib]: https://palletsprojects.com/contributing/ diff --git a/docs/contributing.rst b/docs/contributing.rst index e582053e..d44f865f 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1 +1,8 @@ -.. include:: ../CONTRIBUTING.rst +Contributing +============ + +See the Pallets `detailed contributing documentation <_contrib>`_ for many ways +to contribute, including reporting issues, requesting features, asking or +answering questions, and making PRs. + +.. _contrib: https://palletsprojects.com/contributing/