From f3f34745eadf7e13315a5da5a4e94384ea5d8d47 Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 30 May 2024 16:48:41 -0700 Subject: [PATCH 1/5] Add Contributing guideline --- CONTRIBUTING.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9c4d8dc4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing Guidelines + +PySCF-forge repository is a place where new methodologies, pilot features, and +testing functionalities can be developed and tested before being integrated into +the PySCF core branch (https://github.com/pyscf/pyscf). The PySCF core branch is +supposed to serve methods that have been published and widely used. + +When you install both the PySCF and PySCF-forge packages, you can access the +features of PySCF-forge using `from pyscf import ...` statement, just like you +would access the regular features in the PySCF core branch. + +You might have noticed several PySCF extensions hosted in the PySCF organization +page on GitHub (https://github.com/pyscf). These extensions are created to +decouple compilation and maintenance efforts from the PySCF core branch. They +are expected to follow the same standards of documentation, testing, +cross-Python-version compatibility, and maintenance requirements as the core +branch. You are welcome to release new features as PySCF extensions. If you +choose to develop features as PySCF extensions, please contact any PySCF +maintainers at https://github.com/orgs/pyscf/people . + +## Principles + +* Tests, documentation and compatibility with multiple Python versions are not + mandatory as in the PySCF core branch. However, it is still recommended to + include well-designed tests, examples, documentations to help users to + understand the new feature. + +* The standard for merging pull requests. + A code review will still be required for pull requests (PR) for PySCF-forge. + Please update the code appropriately based on reviewers' suggestions. + The PR will not be merged until all comments are addressed. Additionally, + there is a quick static code check for the code that should all pass. + +* Avoiding filename and module conflicts. + PySCF-forge manages sub-packages through the mechanism "named packages". + When installing PySCF-forge, the sub-packages will be installed in the same directory as PySCF. + This ensures that these features can be accessed within the same namespace as PySCF. + If any packages or files have the same name as those in PySCF, they will overwrite the existing ones. + For example, if you create a `pyscf-forge/pyscf/__init__.py` file, it will + replace the existing `__init__.py` file in PySCF and may lead to PySCF runtime + errors. It is important to avoid creating files or directories that already + exist in the PySCF core branch. + +* Module compatibility and removal policy. + If a module causes installation or compatibility issues with existing modules or + those in the PySCF core branch, a post will be created on GitHub issue board to + address the problem. Features may be removed without notifying to the contributor. + +* Compiling C/C++ extensions + You can utilize CMake or `setuptools.Extension` in setup.py within the + PySCF-forge to compile simple extensions. For complex compiling configurations, + it is advisable to release the feature as a PySCF extension. C/C++ libraries + should be compiled and placed under the directory `pyscf-forge/pyscf/lib`. + This is the location where .so files will be packaged in wheel. + +## How to prompt to PySCF core branch + +After a feature has been added to PySCF-forge for over 6 months, developers can +submit a request to transfer the feature to the PySCF core branch. The proposal +template can be accessed at (TBD). The proposal will be reviewed during the +PySCF board meetings, held approximately every 3 months. + + +-- +Thank you for considering contributing your works to PySCF community! From f449535f8259bd8272e7bf1a8615338ceb49726e Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 30 May 2024 16:51:56 -0700 Subject: [PATCH 2/5] format --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c4d8dc4..cda9ae87 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,5 +61,6 @@ template can be accessed at (TBD). The proposal will be reviewed during the PySCF board meetings, held approximately every 3 months. --- +--- + Thank you for considering contributing your works to PySCF community! From 542302f4f9537a82dbaf5d69aa0d8a8ee23b1493 Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 30 May 2024 20:21:36 -0700 Subject: [PATCH 3/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cda9ae87..50a2c793 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,25 +41,30 @@ maintainers at https://github.com/orgs/pyscf/people . errors. It is important to avoid creating files or directories that already exist in the PySCF core branch. +* Dependencies. + There is no restriction on adding dependencies. However, dependencies can + sometimes leads to conflicts in certain packages. Therefore, please add + dependencies cautiously and only include necessary libraries. If dependencies + cause installation issues, your feature might be removed (see the next rule). + * Module compatibility and removal policy. If a module causes installation or compatibility issues with existing modules or those in the PySCF core branch, a post will be created on GitHub issue board to address the problem. Features may be removed without notifying to the contributor. -* Compiling C/C++ extensions +* Compiling C/C++ extensions. You can utilize CMake or `setuptools.Extension` in setup.py within the PySCF-forge to compile simple extensions. For complex compiling configurations, it is advisable to release the feature as a PySCF extension. C/C++ libraries should be compiled and placed under the directory `pyscf-forge/pyscf/lib`. This is the location where .so files will be packaged in wheel. -## How to prompt to PySCF core branch +## How to transfer a feature to PySCF core branch? After a feature has been added to PySCF-forge for over 6 months, developers can -submit a request to transfer the feature to the PySCF core branch. The proposal -template can be accessed at (TBD). The proposal will be reviewed during the -PySCF board meetings, held approximately every 3 months. - +open an issue to request transferring the feature to the PySCF core branch. +The proposal template can be accessed at (TBD). The proposal will be reviewed +during the PySCF board meetings, held approximately every 3 months. --- From c4eec45217a537d0246e79cd01d2d31c57a190f0 Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 30 May 2024 22:03:47 -0700 Subject: [PATCH 4/5] typo --- CONTRIBUTING.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50a2c793..bb993b0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,14 +32,15 @@ maintainers at https://github.com/orgs/pyscf/people . there is a quick static code check for the code that should all pass. * Avoiding filename and module conflicts. - PySCF-forge manages sub-packages through the mechanism "named packages". - When installing PySCF-forge, the sub-packages will be installed in the same directory as PySCF. - This ensures that these features can be accessed within the same namespace as PySCF. - If any packages or files have the same name as those in PySCF, they will overwrite the existing ones. - For example, if you create a `pyscf-forge/pyscf/__init__.py` file, it will - replace the existing `__init__.py` file in PySCF and may lead to PySCF runtime - errors. It is important to avoid creating files or directories that already - exist in the PySCF core branch. + PySCF-forge manages sub-packages through the mechanism "namespace packages". + When installing PySCF-forge, the sub-packages will be installed in the same + directory as PySCF. This ensures that these features can be accessed within + the same namespace as PySCF. If any packages or files have the same name as + those in PySCF, they will overwrite the existing ones. For example, if you + create a `pyscf-forge/pyscf/__init__.py` file, it will replace the existing + `__init__.py` file in PySCF and may lead to PySCF runtime errors. It is + important to avoid creating files or directories that already exist in the + PySCF core branch. * Dependencies. There is no restriction on adding dependencies. However, dependencies can From 5384a461ae4f4e615033940ad110598fe9af3757 Mon Sep 17 00:00:00 2001 From: gkc1000 Date: Fri, 31 May 2024 14:50:48 +0800 Subject: [PATCH 5/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb993b0f..7e828fdc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,28 @@ # Contributing Guidelines -PySCF-forge repository is a place where new methodologies, pilot features, and -testing functionalities can be developed and tested before being integrated into -the PySCF core branch (https://github.com/pyscf/pyscf). The PySCF core branch is -supposed to serve methods that have been published and widely used. +The PySCF-forge repository is a place to stage new methodologies that may one day be incorporated +into the PySCF core branch (https://github.com/pyscf/pyscf). By placing your code into PySCF-forge, +existing PySCF maintainers will have a chance to comment on the code and work with you to assess the feasibility and +suitability for the core. Placing your code in PySCF-forge means that pull requests +have to be approved by an existing PySCF maintainer, so it is not the place for code that is in +the earliest stages of development. Code in PySCF-forge does not necessarily make it into the core branch: this requires +explicit approval from the board (see below). Note that the PySCF core branch is +intended only for methods that have been published and are widely used (or have the clear potential for wide use). When you install both the PySCF and PySCF-forge packages, you can access the features of PySCF-forge using `from pyscf import ...` statement, just like you would access the regular features in the PySCF core branch. You might have noticed several PySCF extensions hosted in the PySCF organization -page on GitHub (https://github.com/pyscf). These extensions are created to -decouple compilation and maintenance efforts from the PySCF core branch. They -are expected to follow the same standards of documentation, testing, +page on GitHub (https://github.com/pyscf). These extensions have been created to +decouple compilation and maintenance efforts from the PySCF core branch. +They are expected to follow the same standards of documentation, testing, cross-Python-version compatibility, and maintenance requirements as the core -branch. You are welcome to release new features as PySCF extensions. If you -choose to develop features as PySCF extensions, please contact any PySCF -maintainers at https://github.com/orgs/pyscf/people . +branch, but the PySCF maintainers do not actively ensure these standards are met. +Most new features which are built using PySCF, but which do not affect the core functionality, are best released as extensions, +and you always welcome to do so. If you +choose to develop a feature as a PySCF extension, please contact any of the PySCF +maintainers at https://github.com/orgs/pyscf/people. ## Principles @@ -29,10 +35,10 @@ maintainers at https://github.com/orgs/pyscf/people . A code review will still be required for pull requests (PR) for PySCF-forge. Please update the code appropriately based on reviewers' suggestions. The PR will not be merged until all comments are addressed. Additionally, - there is a quick static code check for the code that should all pass. + there is a quick static code check, which the code should pass. * Avoiding filename and module conflicts. - PySCF-forge manages sub-packages through the mechanism "namespace packages". + PySCF-forge manages sub-packages through the mechanism of "namespace packages". When installing PySCF-forge, the sub-packages will be installed in the same directory as PySCF. This ensures that these features can be accessed within the same namespace as PySCF. If any packages or files have the same name as @@ -51,7 +57,7 @@ maintainers at https://github.com/orgs/pyscf/people . * Module compatibility and removal policy. If a module causes installation or compatibility issues with existing modules or those in the PySCF core branch, a post will be created on GitHub issue board to - address the problem. Features may be removed without notifying to the contributor. + address the problem. Features may be removed without notifying the contributor. * Compiling C/C++ extensions. You can utilize CMake or `setuptools.Extension` in setup.py within the @@ -60,13 +66,15 @@ maintainers at https://github.com/orgs/pyscf/people . should be compiled and placed under the directory `pyscf-forge/pyscf/lib`. This is the location where .so files will be packaged in wheel. -## How to transfer a feature to PySCF core branch? +## How to transfer a feature to the PySCF core branch? After a feature has been added to PySCF-forge for over 6 months, developers can -open an issue to request transferring the feature to the PySCF core branch. +open an issue to request to transfer the feature to the PySCF core branch. The proposal template can be accessed at (TBD). The proposal will be reviewed -during the PySCF board meetings, held approximately every 3 months. +during the PySCF board meetings, held approximately every 3 months. If it is decided that +the feature is incompatible with the requirements of the core branch, the board may recommend +additional modifications, or that the feature be removed from PySCF-forge. --- -Thank you for considering contributing your works to PySCF community! +Thank you for considering contributing your work to the PySCF community!