From 4d1770bc22080445f81ec521c13ccfbf013f86cd Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Tue, 7 May 2024 17:38:53 +1200 Subject: [PATCH 01/12] Home page update --- source/index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/index.md b/source/index.md index c573339a..ac924c68 100644 --- a/source/index.md +++ b/source/index.md @@ -12,10 +12,10 @@ Describe your tax and benefit system, provide a situation as input (i.e income), Economists and lawmakers make use of OpenFisca to calculate the effects of policies. By combining them with survey data to simulate the impact of reform on a given government’s budget and a population’s standard of living. * **Developers and companies**: -Developers and companies use Openfisca to effortlessly create web applications based on simulation results with the help of the OpenFisca [web API](openfisca-web-api/index.md). You can build a great significant variety of services by coding formulas, hosting your instances and building your extensions. +Developers and companies use Openfisca to effortlessly create web applications based on simulation results with the help of the OpenFisca [web API](openfisca-web-api/index.md). You can build a significant variety of services by coding formulas, hosting your instances and building your extensions. * **Public administrations**: -Stop building your micro-simulation software and tax & benefit calculators from scratch. Join OpenFisca, contribute to OpenFisca, collaborate with other administrations and reduce costs paid by the taxpayers. +Stop building your micro-simulation software and tax & benefit calculators from scratch. Join OpenFisca, contribute to OpenFisca, collaborate with other administrations and contribute to the practice of shared and open interpretations of legislation. ## Way to use OpenFisca @@ -27,10 +27,10 @@ To get started, you can: * [Build a new tax and benefit system](coding-the-legislation/bootstrapping_a_new_country_package.md) if it doesn’t exist already. * [Contribute](contribute/index.md) to an existing system by adding or improving elements of the legislation. -Then, you will make legal code executable by writing it in the OpenFisca [DSL](https://en.wikipedia.org/wiki/Domain-specific_language), which is a subset of the Python programming language with dedicated functions and tools specifically targeted at modelling rules: +Then, you can make legal code executable by writing it in the OpenFisca [DSL](https://en.wikipedia.org/wiki/Domain-specific_language), which is a subset of the Python programming language with dedicated functions and tools specifically targeted at modelling rules: -* First, identify some legislation that can be expressed as an arithmetic operation. -* Then, translate them into [formulas, variables, parameters, etc.](coding-the-legislation/index.md) +* First, identify some legislation that includes arithmetic operations. +* Then, translate it into [formulas, variables, parameters, etc.](coding-the-legislation/index.md) * [Build some tests](coding-the-legislation/writing_yaml_tests.md) to verify your implementation of the law. * Lost? You are not the first one to go through that! You can [find help](find-help.md) by reaching out to the community. @@ -38,22 +38,22 @@ Then, you will make legal code executable by writing it in the OpenFisca [DSL](h With OpenFisca, you can calculate the effect of legislation on a single situation or a whole population by running a [simulation](simulate/index.md). Since the data you need depends on what you are trying to calculate, OpenFisca does not offer any data upfront. -The following could be your use case to use OpenFisca: +The following is an example OpenFisca use case: Do you want to help users find their eligibility for a social benefit in your country? Then, use OpenFisca to build a user interface asking them for their income and demographic information and provide them with an answer! (Do not forget to comply with GDPR!). -Are you trying to assess the impact of a new housing tax on behalf of the OECD? Find your government's open survey data and use it with OpenFisca to simulate the effect of that tax reform on the poorest 20% of a country. +Are you trying to assess the impact of a new housing tax on behalf of the OECD? Find your government's open survey data and use it with OpenFisca to simulate the effect of that tax reform on the poorest 20% of your country. ### 3 - Run Simulations With OpenFisca there are two ways to calculate the effect of the rules modelled in a country package on a given input data: * If you have a background in web development or want to build a web application with the results of your simulation, you’ll want to use the [web API](openfisca-web-api/index.md). -* If you have a background in datascience, want to use large datasets, or want to dynamically apply changes to the system, you’ll rather use the [Python API](openfisca-python-api/index.md). +* If you have a background in data science, want to use large datasets, or want to dynamically apply changes to the system, you should use the [Python API](openfisca-python-api/index.md). The output of this simulation will be either Python objects or JSON. To represent these results in a graphical format, you can make use of Python libraries such as [plot.ly](https://plot.ly). -Please make sure you read our [license](license.md) before publishing results based on OpenFisca. +Please ensure you read our [licence](license.md) before publishing results based on OpenFisca. ## What OpenFisca will not do for you From 28ce920475fffdc1cddd391025308f08f9314aae Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Tue, 7 May 2024 17:39:09 +1200 Subject: [PATCH 02/12] Licence page update --- source/license.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/license.md b/source/license.md index 521c394b..9b30cef0 100644 --- a/source/license.md +++ b/source/license.md @@ -1,6 +1,6 @@ -# License +# Licence -OpenFisca is a free software made available under the [AGPL license](https://choosealicense.com/licenses/agpl-3.0/). This means that you are free to use, install and modify it with the promise to contribute back your changes to the community. This is the only way a contributive digital common can be made sustainable. +OpenFisca is free software made available under the [AGPL licence](https://choosealicense.com/licenses/agpl-3.0/). This means that you are free to use, install and modify it with the promise to contribute back your changes to the community. This is the only way a contributive digital common can be made sustainable. All contributions are welcome as long as they abide by our contribution guidelines. We are happy to have you here in the OpenFisca community. ## Computation results @@ -27,7 +27,7 @@ The following HTML snippet can be used to credit OpenFisca in your articles and ## Hosting an API instance -If you provide a service that uses OpenFisca, either bundled in a program or serving it over the network, be it directly or wrapped through another API layer, you have to credit OpenFisca, by providing a link to its source code and license. +If you provide a service that uses OpenFisca, either bundled in a program or serving it over the network, be it directly or wrapped through another API layer, you have to credit OpenFisca, by providing a link to its source code and licence. The following HTML snippet can be used to credit OpenFisca, for example by placing it in your footer or “about” page. Please make sure to update the destination of the source code link if you use a modified version! @@ -38,7 +38,7 @@ Please make sure to update the destination of the source code link if you use a Computations powered by OpenFisca, whose source code - is used under an AGPL license. + is used under an AGPL licence. ``` @@ -58,4 +58,4 @@ If you modify or extend OpenFisca, you are [legally required](https://choosealic You can read [this analysis](https://softwareengineering.stackexchange.com/questions/107883/agpl-what-you-can-do-and-what-you-cant/314908/) to get more insight into what you can and can't do with APGL-licensed software. -If you see opportunities in developing services/businesses/tools on top of OpenFisca but are concerned with the AGPL3 license implications, please [open an issue](https://github.com/openfisca/openfisca-core/issues/new) to have a public discussion on the topic. +If you see opportunities in developing services/businesses/tools on top of OpenFisca but are concerned with the AGPL3 licence implications, please [open an issue](https://github.com/openfisca/openfisca-core/issues/new) to have a public discussion on the topic. From f6e5b9bf3142cf75c17d8ea858f72ed7dfb55fa5 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Tue, 7 May 2024 20:46:13 +1200 Subject: [PATCH 03/12] Find help --- source/find-help.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/find-help.md b/source/find-help.md index 796abfb2..1e7a3d70 100644 --- a/source/find-help.md +++ b/source/find-help.md @@ -16,14 +16,14 @@ The following prefixes are used before channel names to increase discoverability The following suffix conventions are used on tax and benefit system models by OpenFisca for better clarity: -- Channels that centralize discussion around a specific tax and benefit system are suffixed with `-system`. +- Channels that centralise discussion around a specific tax and benefit system are suffixed with `-system`. _For example- `france-system`_. *Note: If the full name is too long for the Slack channel character limit, then a shortened version of the name is used. -- Channels that centralize discussions around extensions to tax and benefit systems are given that system’s module name, followed by `-ext-` and an identifier for that extension. +- Channels that centralise discussions around extensions to tax and benefit systems are given that system’s module name, followed by `-ext-` and an identifier for that extension. _For example- `france-ext-paris`_. -- Channels for the system-specific groups are campfires around which some specific organizations of contributors to a tax and benefit system gather. When a country becomes large enough, it so often happens that several contributors work concurrently on different parts of the system, and the main `-system` channel becomes unreadable. These channels are then modified by the system’s module name, followed by `-org-` and an identifier for that group. _For example `france-org-gouv`_. +- Channels for the system-specific groups are campfires around which some specific organisations of contributors to a tax and benefit system gather. When a country becomes large enough, it so often happens that several contributors work concurrently on different parts of the system, and the main `-system` channel becomes unreadable. These channels are then modified by the system’s module name, followed by `-org-` and an identifier for that group. _For example `france-org-gouv`_. ## Contact From 47fbb661a5061227bcf72cf720f7e1b2285a3d7c Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Wed, 8 May 2024 13:59:21 +1200 Subject: [PATCH 04/12] how to docker --- source/installation/howto_docker.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/installation/howto_docker.md b/source/installation/howto_docker.md index 0f2341ec..21a2f059 100644 --- a/source/installation/howto_docker.md +++ b/source/installation/howto_docker.md @@ -1,13 +1,13 @@ # With Docker -When you want to use OpenFisca, either to run it or edit its code, you need to setup a specific environement. +When you want to use OpenFisca, either to run it or edit its code, you need to set up a specific environment. If you don't want the OpenFisca environment to interfere with your pre-existing setup, or if you don't have one, you can use a container platform such as [Docker](https://www.docker.com) that will set everything up for you. -> On Windows operating system, you need to have Windows 10 or higher to use Docker. +> On Windows operating systems, you need to have Windows 10 or higher to use Docker. ## Install Docker -Docker allows you to run a minimal image of Unix operating system. +Docker allows you to run a minimal image of an operating system. In this docker container, you will have an isolated environment with user rights to install OpenFisca. * Install free [Docker Community Edition](https://docs.docker.com/install/#supported-platforms) (also named `Docker Desktop`). @@ -16,7 +16,7 @@ In this docker container, you will have an isolated environment with user rights ## Install OpenFisca in a Docker container -Let's say that you want to install the [openfisca-country-template](https://github.com/openfisca/country-template) model (or your specific country model). And you want to work in a directory named `my-openfisca` where any change you do is visible on both sides, locally and on Docker. +Let's say that you want to install the [openfisca-country-template](https://github.com/openfisca/country-template) model (or your specific country model). You also want to work in a directory named `my-openfisca` where any change you do is visible on both sides, locally and on Docker. 1. Go to your working directory: - If you don't have one, create a new directory named `my-openfisca`. @@ -27,19 +27,19 @@ Let's say that you want to install the [openfisca-country-template](https://gith cd my-openfisca # Updated with the real path to your working directory ``` -2. Build a container with Python 3.7, Git and console commands. +2. Build a container with Python 3.9, Git and console commands. > Git comes with Python image. - For Linux/Unix/Mac operating systems, run: ```sh - docker run --rm -it -v $PWD:/my-openfisca -w /my-openfisca python:3.7 bash + docker run --rm -it -v $PWD:/my-openfisca -w /my-openfisca python:3.9 bash ``` - For Windows operating system, run: ```sh - docker run --rm -it -v %cd%:/my-openfisca -w /my-openfisca python:3.7 bash + docker run --rm -it -v %cd%:/my-openfisca -w /my-openfisca python:3.9 bash ``` 3. Check for installed libraries with `pip list` command. From 8b76f4f3bb4287d0eb2e50be3172249a07acb735 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Thu, 9 May 2024 17:22:24 +1200 Subject: [PATCH 05/12] Initial updates to Contribute section excluding Tests --- source/contribute/commit-messages.md | 8 ++++---- source/contribute/developer-guide.md | 8 ++++++-- source/contribute/documentation.md | 2 +- source/contribute/extensions.md | 4 ++-- source/contribute/guidelines.md | 12 ++++++------ source/contribute/language.md | 2 +- source/contribute/semver.md | 2 +- source/contribute/variables-naming.md | 14 ++++++-------- 8 files changed, 27 insertions(+), 25 deletions(-) diff --git a/source/contribute/commit-messages.md b/source/contribute/commit-messages.md index d02bced4..66dff62f 100644 --- a/source/contribute/commit-messages.md +++ b/source/contribute/commit-messages.md @@ -2,11 +2,11 @@ ## Variable name changes -To avoid OpenFisca users to be surprised by a non expected variable renaming breaking their code, we use standard commit messages when renaming a variable. The syntax is formalized below. It must be respected precisely, to allow automatic information extraction. +To avoid OpenFisca users being surprised by the unexpected renaming of a variable that breaks their code, we use standard commit messages when renaming a variable. The syntax is formalised below. It must be respected precisely, to allow automatic information extraction. ### Renaming -Renaming one or several variables will be notified by a commit message with the following syntax, **on one independent line per renamed variable**: +Renaming one or several variables will be notified by a commit message that utilises **one independent line per renamed variable** with the following syntax: ```text Rename former_name to new_name @@ -16,7 +16,7 @@ No other information must appear on this line. ### Introducing -Introducing one or several new variables will be notified by a commit message with the following syntax, **on one idependant line per created variable**: +Introducing one or several new variables will be notified by a commit message that utilises, **one independant line per created variable** with the following syntax: ```text Introduce new_name @@ -26,7 +26,7 @@ No other information must appear on this line. ### Deprecating -If a variable must not be used anymore, it will be notified by a commit message with the following syntax, **on one idependant line per deprecated variable**: +If a variable must not be used anymore, it will be notified by a commit message that utilises **one independant line per deprecated variable** with the following syntax: ```text Deprecate former_name diff --git a/source/contribute/developer-guide.md b/source/contribute/developer-guide.md index 641a3cf9..1628b012 100644 --- a/source/contribute/developer-guide.md +++ b/source/contribute/developer-guide.md @@ -5,7 +5,11 @@ The OpenFisca project is distributed across many Git repositories: * [OpenFisca-Core](https://github.com/openfisca/openfisca-core) -* [OpenFisca-France](https://github.com/openfisca/openfisca-france) +* [Country-Template](https://github.com/openfisca/country-template) +* [OpenFisca-Documentation](https://github.com/openfisca/openfisca-doc) +* [Legislation-Explorer](https://github.com/openfisca/legislation-explorer) +* [OpenFisca-Survey-Manager](https://github.com/openfisca/openfisca-survey-manager) +* [OpenFisca-France](https://github.com/openfisca/openfisca-france) and other models etc. ## Debugging code @@ -43,7 +47,7 @@ To profile the execution of a portion of code, wrap it with these lines: ``` Each time you call the endpoint a `result.profile` file is written. -To prevent it to be overwritten, generate a dynamic name with [`tempfile.mkstemp`](https://docs.python.org/2/library/tempfile.html#tempfile.mkstemp). +To prevent it being overwritten, generate a dynamic name with [`tempfile.mkstemp`](https://docs.python.org/2/library/tempfile.html#tempfile.mkstemp). Then you can use the [runsnakerun](http://www.vrplumber.com/programming/runsnakerun/) GUI to inspect the profile data. diff --git a/source/contribute/documentation.md b/source/contribute/documentation.md index 947c1582..605b6c8b 100644 --- a/source/contribute/documentation.md +++ b/source/contribute/documentation.md @@ -6,7 +6,7 @@ and the source is hosted on this GitHub repository: ## Collaborative editing -Everybody can participate to the redaction of the documentation. +Everybody can participate in the redaction of the documentation. On each page there is a link named "Edit this page". Just click on it and you'll jump on GitHub on the Markdown source file of the page. diff --git a/source/contribute/extensions.md b/source/contribute/extensions.md index 36e90e62..a60bb8c3 100644 --- a/source/contribute/extensions.md +++ b/source/contribute/extensions.md @@ -1,6 +1,6 @@ # OpenFisca extensions -Extensions allow you to define new variables or parameters for a tax and benefit system, while keeping their code separated from the main country package. They can only _add_ variables and parameters to the tax and benefit system: they cannot _modify_ or _neutralize_ existing ones. +Extensions allow you to define new variables or parameters for a tax and benefit system, while keeping their code separated from the main country package. They can only _add_ variables and parameters to the tax and benefit system: they cannot _modify_ or _neutralise_ existing ones. They are for instance used to code local benefits. @@ -28,4 +28,4 @@ All python files located directly in `{extension_name}/` are imported in the tax The syntax of the formulas within extension python files is the same than in the general country package formulas (e.g. `from openfisca_france.model.base import *`). -Variables inside an extension should not have the same name than any existing formula, nor than any formula in another extension being used. +Variables inside an extension should not have the same name as any existing formula, nor as any formula in another extension being used. diff --git a/source/contribute/guidelines.md b/source/contribute/guidelines.md index c5d1f9ee..18f75bf2 100644 --- a/source/contribute/guidelines.md +++ b/source/contribute/guidelines.md @@ -20,15 +20,15 @@ Each OpenFisca repository has its own issues. See [OpenFisca repositories](https - If you modify/create/delete a simulation variable, please follow the [commit message rules](commit-messages.md). - When adding new variables, please consider the [naming guidelines](variables-naming.md). - Your code should be tested, if feasible: - + bugfixes should include regression tests - + new behavior should at least get minimal exercise + + bug fixes should include regression tests + + new behaviour should at least get minimal exercise - Use atomic commits, in particular try to isolate "code-cleanup" commits ### Opening a Pull Request -- All code contributions are submitted via a Pull Request towards `master`. The `master` branches are thus [protected](https://help.github.com/articles/about-protected-branches/). +- All code contributions are submitted via a Pull Request towards `main`. The `main` branches are thus [protected](https://help.github.com/articles/about-protected-branches/). - Opening a Pull Request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer. -- If the Pull Request depends on another opened Pull Request on another repository (like OpenFisca-Core/OpenFisca-France), the requirements should be updated in the dependent project via its `setup.py`. +- If the Pull Request depends on another opened Pull Request on another repository (like OpenFisca-Core/OpenFisca-France), the requirements should be updated in the dependent project via its `pyproject.toml`. It is considered a good practice to begin the name of the pull request with a verb in the present imperative tense: @@ -59,14 +59,14 @@ Due to a `pip` limitation, it is required to increment the major version number #### Peer reviews -Pull requests should generally be **reviewed** by someone else than their authors. +Pull requests should generally be **reviewed** by someone other than their authors. This is mandatory for: - Any Pull Request with **breaking changes** on `openfisca-france`, `openfisca-web-api`. - Any Pull Request bringing **new features**, if these features are not relative to a specific scope. + Adding a new route to the API **requires** a review. - + A review is yet not mandatory to add a new formula to social contributions in `openfisca-france`. It is though recommended. + + A review is not yet mandatory to add a new formula to social contributions in `openfisca-france`. It is though recommended. To help reviewers, make sure to add to your PR a **clear text explanation** of your changes. diff --git a/source/contribute/language.md b/source/contribute/language.md index 71995587..192a4581 100644 --- a/source/contribute/language.md +++ b/source/contribute/language.md @@ -4,7 +4,7 @@ The development language is English. All comments and documentation in common re ## Country-specific repositories -Some repositories define the tax and benefit system of a specific country. In such cases, the language used throughout issues and pull requests should be one of the native ones of that country. +Some repositories define the tax and benefit system of a specific country. In such cases, the language used throughout issues and pull requests should be one of the native languages of that country. For instance, `openfisca-france` issues and pull-requests should be written in French. diff --git a/source/contribute/semver.md b/source/contribute/semver.md index e96d3bc7..97e87e08 100644 --- a/source/contribute/semver.md +++ b/source/contribute/semver.md @@ -31,4 +31,4 @@ It is thus crucial to determine whether your changes are **backwards-compatible* - Renaming or deprecating a variable. - Changing the default value of a variable. - Deprecating a parameter. -- Changing the sctructure of the parameter tree. +- Changing the structure of the parameter tree. diff --git a/source/contribute/variables-naming.md b/source/contribute/variables-naming.md index 26812ef9..7fe8e428 100644 --- a/source/contribute/variables-naming.md +++ b/source/contribute/variables-naming.md @@ -2,7 +2,7 @@ ## General philosophy -The discussion below is concerned with naming the variables of a country package. In that case, the ["local language rule"](language.md) applies, and the appropriate language for modeling the domain is one of the native ones of the modeled country. We consider each tax, collecting organism and country regulation, and so on, as a domain-specific term. In the same fashion, well-known abbreviations of these domain-specific terms are accepted. +The discussion below is concerned with naming the variables of a country package. In that case, the ["local language rule"](language.md) applies, and the appropriate language for modelling the domain is one of the native ones of the modelled country. We consider each tax, collecting organism and country regulation, and so on, as a domain-specific term. In the same fashion, well-known abbreviations of these domain-specific terms are accepted. OpenFisca variables names should, as much as possible, be understandable by an external contributor who is **curious** about the country's tax and benefit system, **without necessarily being an expert**. @@ -19,22 +19,20 @@ A particular effort should be made on variables that are likely to be reused. #### Bad naming - `vat_sub1`: In English-speaking countries VAT would unambiguously refer to Value Added Tax, but the addition of a suffix for technical purposes (e.g. an intermediate step in the computation) should in -general be avoided. A better name might be `vat_on_exports` (assuming this is the intermediate step's -meaning). -- `cpstd`. Here the acronym might mean "Company Paid Short-Term Disability", but this acronym is not widely used or recognizable, and will not be found in a web search. Using a longer name is preferable. +general be avoided. A better name might be `vat_on_exports` (assuming this is the intermediate step's meaning). +- `cpstd`. Here the acronym might mean "Company Paid Short-Term Disability", but this acronym is not widely used or recognisable, and will not be found in a web search. Using a longer name is preferable. ## Do's and don'ts ### Acronyms -Acronyms are OK as long as they are broadly accepted and their meaning is quickly findable online. A good -test for "findable" is that a web search _from the relevant country_ should turn up the intended meaning as the first or second hit. +Acronyms are OK as long as they are broadly accepted and their meaning is quickly findable online. A good test for "findable" is that a web search _from the relevant country_ should turn up the intended meaning as the first or second hit. #### Good naming - `VAT` (Value Added Tax, near-universal except in France) - `EBITDA` (tax, unambiguous) -- `RSA` (French, social benefit rather than cryptography, recognizable in context) +- `RSA` (French, social benefit rather than cryptography, recognisable in context) #### Bad naming @@ -90,4 +88,4 @@ This is often seen when aggregating from the individual level to e.g. the househ ## Legacy -Some existing models (such as the France model, grown over several years) do not respect all the guidelines presented here. These guidelines may also evolve with improvements to the underlying computation engine (such as namespacing or improved approaches to aggregation and other relations between entity and group values). Since variables and parameters represent the external API of a model, and excessive migration labor may discourage the users of an API, it is preferable to avoid global renamings. However, new names should be compliant with these guidelines, and legacy ones should be improved progressively and opportunistically. Communicating your standards to contributors is an important part of maintaining your model. +Some existing models (such as the France model, grown over several years) do not respect all the guidelines presented here. These guidelines may also evolve with improvements to the underlying computation engine (such as namespacing or improved approaches to aggregation and other relations between entity and group values). Since variables and parameters represent the external API of a model, and excessive migration labour may discourage the users of an API, it is preferable to avoid global renaming. However, new names should be compliant with these guidelines, and legacy ones should be improved progressively and opportunistically. Communicating your standards to contributors is an important part of maintaining your model. From 52a4f515b5daa855f812c6cedc81ffeeb85fbc13 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Sun, 19 May 2024 19:45:12 +1200 Subject: [PATCH 06/12] Update source/contribute/commit-messages.md Co-authored-by: Matti Schneider --- source/contribute/commit-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/commit-messages.md b/source/contribute/commit-messages.md index 66dff62f..502b3fcc 100644 --- a/source/contribute/commit-messages.md +++ b/source/contribute/commit-messages.md @@ -16,7 +16,7 @@ No other information must appear on this line. ### Introducing -Introducing one or several new variables will be notified by a commit message that utilises, **one independant line per created variable** with the following syntax: +Introducing one or several new variables will be notified by a commit message that utilises, **one separate line per created variable** with the following syntax: ```text Introduce new_name From 693578c3311ce73b92c42f2d5881f44dacf04104 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Sun, 19 May 2024 19:45:31 +1200 Subject: [PATCH 07/12] Update source/contribute/developer-guide.md Co-authored-by: Matti Schneider --- source/contribute/developer-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/developer-guide.md b/source/contribute/developer-guide.md index 1628b012..c74c4d16 100644 --- a/source/contribute/developer-guide.md +++ b/source/contribute/developer-guide.md @@ -47,7 +47,7 @@ To profile the execution of a portion of code, wrap it with these lines: ``` Each time you call the endpoint a `result.profile` file is written. -To prevent it being overwritten, generate a dynamic name with [`tempfile.mkstemp`](https://docs.python.org/2/library/tempfile.html#tempfile.mkstemp). +To prevent it from being overwritten, generate a dynamic name with [`tempfile.mkstemp`](https://docs.python.org/2/library/tempfile.html#tempfile.mkstemp). Then you can use the [runsnakerun](http://www.vrplumber.com/programming/runsnakerun/) GUI to inspect the profile data. From 56fd424d854314ed216c95896b2efb87d5ec5370 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Sun, 19 May 2024 19:45:53 +1200 Subject: [PATCH 08/12] Update source/contribute/commit-messages.md Co-authored-by: Matti Schneider --- source/contribute/commit-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/commit-messages.md b/source/contribute/commit-messages.md index 502b3fcc..017b2a8d 100644 --- a/source/contribute/commit-messages.md +++ b/source/contribute/commit-messages.md @@ -26,7 +26,7 @@ No other information must appear on this line. ### Deprecating -If a variable must not be used anymore, it will be notified by a commit message that utilises **one independant line per deprecated variable** with the following syntax: +If a variable must not be used anymore, it will be notified by a commit message that utilises **one separate line per deprecated variable** with the following syntax: ```text Deprecate former_name From 3afe87ef780a0a34f27b0fdc78bbbf44157fad1c Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Mon, 20 May 2024 17:26:02 +1200 Subject: [PATCH 09/12] Apply suggestions from code review Co-authored-by: Matti Schneider --- source/contribute/documentation.md | 2 +- source/contribute/guidelines.md | 5 ++--- source/contribute/variables-naming.md | 4 ++-- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/source/contribute/documentation.md b/source/contribute/documentation.md index 605b6c8b..4ea6fa0b 100644 --- a/source/contribute/documentation.md +++ b/source/contribute/documentation.md @@ -6,7 +6,7 @@ and the source is hosted on this GitHub repository: ## Collaborative editing -Everybody can participate in the redaction of the documentation. +Every reader is encouraged to participate in the improvement of the documentation. On each page there is a link named "Edit this page". Just click on it and you'll jump on GitHub on the Markdown source file of the page. diff --git a/source/contribute/guidelines.md b/source/contribute/guidelines.md index 18f75bf2..7452f5a8 100644 --- a/source/contribute/guidelines.md +++ b/source/contribute/guidelines.md @@ -28,7 +28,7 @@ Each OpenFisca repository has its own issues. See [OpenFisca repositories](https - All code contributions are submitted via a Pull Request towards `main`. The `main` branches are thus [protected](https://help.github.com/articles/about-protected-branches/). - Opening a Pull Request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer. -- If the Pull Request depends on another opened Pull Request on another repository (like OpenFisca-Core/OpenFisca-France), the requirements should be updated in the dependent project via its `pyproject.toml`. +- If the Pull Request depends on another opened Pull Request on another repository (like Core or some country model), the requirements should be updated in the dependent project via its `pyproject.toml` (or `setup.py` for older codebases). It is considered a good practice to begin the name of the pull request with a verb in the present imperative tense: @@ -59,14 +59,13 @@ Due to a `pip` limitation, it is required to increment the major version number #### Peer reviews -Pull requests should generally be **reviewed** by someone other than their authors. +Pull requests should be **reviewed** by someone other than their authors. This is mandatory for: - Any Pull Request with **breaking changes** on `openfisca-france`, `openfisca-web-api`. - Any Pull Request bringing **new features**, if these features are not relative to a specific scope. + Adding a new route to the API **requires** a review. - + A review is not yet mandatory to add a new formula to social contributions in `openfisca-france`. It is though recommended. To help reviewers, make sure to add to your PR a **clear text explanation** of your changes. diff --git a/source/contribute/variables-naming.md b/source/contribute/variables-naming.md index 7fe8e428..f26b1c0d 100644 --- a/source/contribute/variables-naming.md +++ b/source/contribute/variables-naming.md @@ -26,13 +26,13 @@ general be avoided. A better name might be `vat_on_exports` (assuming this is th ### Acronyms -Acronyms are OK as long as they are broadly accepted and their meaning is quickly findable online. A good test for "findable" is that a web search _from the relevant country_ should turn up the intended meaning as the first or second hit. +Acronyms are OK as long as they are broadly accepted and their meaning is quickly findable online. A good test for "findable" is that a web search _from the relevant country_ should turn up the intended meaning as the first or second result. #### Good naming - `VAT` (Value Added Tax, near-universal except in France) - `EBITDA` (tax, unambiguous) -- `RSA` (French, social benefit rather than cryptography, recognisable in context) +- `RSA` (French social benefit rather than cryptography, recognisable in context) #### Bad naming From d7677aacada92a4b836128fe4eafb132d47d8be1 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Mon, 20 May 2024 17:54:20 +1200 Subject: [PATCH 10/12] Suggested changes --- source/contribute/developer-guide.md | 9 ++++++--- source/contribute/guidelines.md | 6 ++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/source/contribute/developer-guide.md b/source/contribute/developer-guide.md index c74c4d16..c710ead8 100644 --- a/source/contribute/developer-guide.md +++ b/source/contribute/developer-guide.md @@ -2,14 +2,17 @@ ## Source code repositories -The OpenFisca project is distributed across many Git repositories: +OpenFisca is distributed across many Git repositories. There are two types of repositories, those shared by everyone and country/jurisdiction specific repositories. + +Here are some of the main repositories shared by everyone: * [OpenFisca-Core](https://github.com/openfisca/openfisca-core) * [Country-Template](https://github.com/openfisca/country-template) -* [OpenFisca-Documentation](https://github.com/openfisca/openfisca-doc) * [Legislation-Explorer](https://github.com/openfisca/legislation-explorer) * [OpenFisca-Survey-Manager](https://github.com/openfisca/openfisca-survey-manager) -* [OpenFisca-France](https://github.com/openfisca/openfisca-france) and other models etc. +* [OpenFisca Documentation (this site)](https://github.com/openfisca/openfisca-doc) + +These can all be found at [https://github.com/openfisca](https://github.com/openfisca). ## Debugging code diff --git a/source/contribute/guidelines.md b/source/contribute/guidelines.md index 7452f5a8..2dafd32f 100644 --- a/source/contribute/guidelines.md +++ b/source/contribute/guidelines.md @@ -1,6 +1,6 @@ # Contributor guidelines -The OpenFisca project follows the [GitHub Flow](https://guides.github.com/introduction/flow/). +OpenFisca follows the [GitHub Flow](https://guides.github.com/introduction/flow/). Each Python package uses [Semantic Versioning](http://semver.org/). @@ -26,7 +26,9 @@ Each OpenFisca repository has its own issues. See [OpenFisca repositories](https ### Opening a Pull Request -- All code contributions are submitted via a Pull Request towards `main`. The `main` branches are thus [protected](https://help.github.com/articles/about-protected-branches/). +> Note: It is the intention to generally rename `master` branches across OpenFisca to `main` in accordance with industry practice. + +- All code contributions are submitted via a Pull Request towards `master`. The `master` branches are thus [protected](https://help.github.com/articles/about-protected-branches/). - Opening a Pull Request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer. - If the Pull Request depends on another opened Pull Request on another repository (like Core or some country model), the requirements should be updated in the dependent project via its `pyproject.toml` (or `setup.py` for older codebases). From 550dcbfea1a3b9eaeb40d73a1ad66c804c23c535 Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Mon, 20 May 2024 17:56:40 +1200 Subject: [PATCH 11/12] Remove unrequired line break --- source/contribute/variables-naming.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/contribute/variables-naming.md b/source/contribute/variables-naming.md index f26b1c0d..40d0b3a9 100644 --- a/source/contribute/variables-naming.md +++ b/source/contribute/variables-naming.md @@ -18,8 +18,7 @@ A particular effort should be made on variables that are likely to be reused. #### Bad naming -- `vat_sub1`: In English-speaking countries VAT would unambiguously refer to Value Added Tax, but the addition of a suffix for technical purposes (e.g. an intermediate step in the computation) should in -general be avoided. A better name might be `vat_on_exports` (assuming this is the intermediate step's meaning). +- `vat_sub1`: In English-speaking countries VAT would unambiguously refer to Value Added Tax, but the addition of a suffix for technical purposes (e.g. an intermediate step in the computation) should in general be avoided. A better name might be `vat_on_exports` (assuming this is the intermediate step's meaning). - `cpstd`. Here the acronym might mean "Company Paid Short-Term Disability", but this acronym is not widely used or recognisable, and will not be found in a web search. Using a longer name is preferable. ## Do's and don'ts From 94d428a4e7a9ee1c39747f7d5e479538a53977bb Mon Sep 17 00:00:00 2001 From: Hamish Fraser Date: Tue, 21 May 2024 13:42:37 +1200 Subject: [PATCH 12/12] Linting --- source/contribute/guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contribute/guidelines.md b/source/contribute/guidelines.md index 2dafd32f..a2d6b269 100644 --- a/source/contribute/guidelines.md +++ b/source/contribute/guidelines.md @@ -26,7 +26,7 @@ Each OpenFisca repository has its own issues. See [OpenFisca repositories](https ### Opening a Pull Request -> Note: It is the intention to generally rename `master` branches across OpenFisca to `main` in accordance with industry practice. +> Note: It is the intention to generally rename `master` branches across OpenFisca to `main` in accordance with industry practice. - All code contributions are submitted via a Pull Request towards `master`. The `master` branches are thus [protected](https://help.github.com/articles/about-protected-branches/). - Opening a Pull Request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer.