Merge pull request #117 from CosmoStat/add-doc-files

Add doc files

CODE_OF_CONDUCT.md

@@ -0,0 +1,71 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We, as members, contributors, and leaders of the WaveDiff community, pledge to foster an inclusive, respectful, and harassment-free environment for all participants, regardless of age, gender identity and expression, sexual orientation, disability, physical appearance, ethnicity, nationality, religion, or other protected characteristics.
+
+## Our Standards
+
+Examples of behavior that contribute to creating a positive and welcoming environment include:
+
+- Showing empathy and kindness towards others.
+- Respecting diverse viewpoints and experiences.
+- Giving and receiving constructive feedback graciously.
+- Taking responsibility for our actions and learning from mistakes.
+- Prioritizing the well-being and inclusivity of the entire community.
+
+Examples of unacceptable behavior include:
+
+- Use of derogatory language or imagery, and any form of harassment.
+- Personal attacks, trolling, or inflammatory remarks.
+- Public or private harassment, including but not limited to, unwelcome advances or attention.
+- Sharing others' private information without explicit consent.
+- Any conduct that creates an intimidating, hostile, or offensive environment.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for upholding these standards of behavior and will address any instances of unacceptable conduct promptly and fairly. They have the authority to enforce the Code of Conduct by taking appropriate corrective action, including warnings, temporary bans, or permanent expulsion from the community.
+
+## Scope
+
+This Code of Conduct applies to all community spaces, including online forums, mailing lists, social media platforms, and official events or gatherings organized by WaveDiff.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [email protected] and [email protected]. All reports will be reviewed and investigated thoroughly, and appropriate actions will be taken in response.
+
+Community leaders are committed to respecting the privacy and confidentiality of individuals who report incidents and will handle each case with sensitivity and discretion.
+
+## Enforcement Guidelines
+
+In enforcing this Code of Conduct, community leaders will adhere to the following guidelines:
+
+### 1. Correction
+
+**Community Impact**: Behavior that is deemed inappropriate, unprofessional, or unwelcome.
+
+**Consequence**: The individual responsible will receive a private, written warning from community leaders, explaining the nature of the violation and providing guidance on acceptable behavior. A public apology may be requested if deemed necessary.
+
+### 2. Warning
+
+**Community Impact**: A single incident or series of actions that violate community standards.
+
+**Consequence**: A formal warning will be issued, outlining the consequences for continued misconduct. The individual will be restricted from interacting with the affected parties or community leaders for a specified period. Further violations may result in temporary or permanent bans.
+
+### 3. Temporary Ban
+
+**Community Impact**: Serious or sustained violations of community standards.
+
+**Consequence**: The individual will be temporarily banned from participating in community activities, including public communication or interaction with community members, for a designated period. Any attempts to circumvent this ban will result in immediate escalation to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Repeated patterns of misconduct or egregious violations of community standards.
+
+**Consequence**: The individual will be permanently banned from engaging in any form of interaction within the WaveDiff community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, and is inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this Code of Conduct, please refer to the [FAQ](https://www.contributor-covenant.org/faq). Translations are available [here](https://www.contributor-covenant.org/translations).

CONTRIBUTING.md

@@ -0,0 +1,147 @@
+
+# Contributing to WaveDiff
+
+WaveDiff is a software development project aimed at modeling the point spread function of an optical system using auto differentiation techniques. These guidelines are designed to facilitate contributions to WaveDiff by providing clear instructions on issue reporting, pull request submission, and code style standards.
+
+## Contents
+
+1. [Introduction](#introduction)
+2. [Workflow](#workflow)
+3. [Issues](#issues)
+4. [Pull Requests](#pull-requests)
+   1. [Before Opening a PR](#before-opening-a-pr)
+   2. [Opening a PR](#opening-a-pr)
+   3. [Revising a PR](#revising-a-pr)
+   4. [After a PR is Merged](#after-a-pr-is-merged)
+5. [Content](#content)
+6. [CI Tests](#ci-tests)
+7. [Style Guide](#style-guide)
+
+## Introduction
+
+Welcome to the WaveDiff project! We appreciate your interest in contributing to our software development efforts. Before you get started, please take a moment to review and adhere to these guidelines and our [code of conduct](./CODE_OF_CONDUCT.md).
+
+## Workflow
+
+The WaveDiff project follows a [specific workflow](./DEV_WORKFLOW.md) to streamline the development process. Familiarize yourself with the following workflow guidelines:
+
+1. **Milestone Definition**: Define milestones to mark the completion of project cycles, such as feature development or testing phases. Milestones are typically scheduled releases, such as monthly releases, and can include different types such as minor, major, or patch releases.
+
+2. **Git Branching Model**: WaveDiff follows a Git branching model to manage code changes efficiently. The main branches include:
+   - `main`: Stores official release history, with each commit tagged with a version number.
+   - `develop`: Integration branch for features.
+   - `feature`: Branches for developing new features, created from the `develop` branch.
+   - `bug`: Branches for fixing specific bugs, created from the `develop` branch.
+   - `hotfix`: Branches for quickly correcting bugs in the latest release version, created from the `main` branch.
+
+3. **Branch Naming Conventions**: Use specific naming conventions for branches to indicate their purpose and associated issue. For example:
+   - Feature branch: `feature/issue-<issue_number>/short-description`
+   - Bug branch: `bug/issue-<issue_number>/short-description`
+   - Hotfix branch: `hotfix/issue-<issue_number>/short-description`
+
+4. **Pull Request Process**: Follow a structured process when opening and reviewing pull requests. Include steps for opening a PR, revising it based on feedback, and merging it into the appropriate branch.
+
+5. **Preparing for a Release**: Outline the steps to prepare for a release, including merging changes into the main branch and tagging the release.
+
+These workflow guidelines ensure consistency and efficiency in the development process and help maintain a high-quality codebase for the WaveDiff project.
+
+## Issues
+
+Reporting issues is a valuable way to contribute to the improvement of WaveDiff. Follow these guidelines when reporting issues:
+
+- Use the [issue tracker](https://github.com/CosmoStat/wf-psf/issues/new/choose) to report bugs, request features, or ask questions.
+- Provide clear and descriptive titles and descriptions for your issues.
+- Search existing issues to avoid duplicates before submitting a new one.
+
+## Pull Requests
+
+To contribute code changes or new features to WaveDiff, please follow these steps:
+
+### Before Opening a PR
+
+1. Log in to your GitHub account or create one if you don't have one already.
+2. Navigate to the [WaveDiff repository](https://github.com/CosmoStat/wf-psf/).
+3. Check if an [issue](#issues) exists for the changes you plan to make. If not, [open one](https://github.com/CosmoStat/wf-psf/issues/new/choose) and specify that you plan to open a PR to address it.
+4. Fork the repository to create your own copy.
+5. Clone your fork of WaveDiff to your local machine.
+```bash
+git clone [email protected]:<your-username>/wf-psf.git
+```
+6. Add the original repository (upstream) as a remote.
+```bash
+git remote add upstream [email protected]:CosmoStat/wf-psf.git
+```
+
+### Opening a PR
+
+1. Pull the latest updates from the original repository.
+```bash
+git pull upstream develop
+```
+2. Create a new branch for your modifications.
+```bash
+git checkout -b <branch-name>
+```
+3. Make the desired modifications to the codebase.
+4. Add and commit your changes.
+```bash
+git add .
+git commit -m "Description of the changes"
+```
+5. Push your changes to your fork on GitHub.
+```bash
+git push origin <branch-name>
+```
+6. Open a [pull request](https://github.com/CosmoStat/wf-psf/compare) with a clear description of your changes and reference any related issues.
+
+### Revising a PR
+
+1. After opening a PR, a project maintainer will review your changes and provide feedback.
+2. Address any comments or requested changes in your PR.
+3. Push your changes to the same branch in your fork.
+4. The reviewer will merge your PR into the main branch once it's approved.
+
+### After a PR is Merged
+
+After your PR is merged, follow these steps to keep your fork up to date:
+
+1. Switch to your local develop branch.
+```bash
+git checkout develop
+```
+2. Delete the branch you used for the PR.
+```bash
+git branch -d <branch-name>
+```
+3. Pull the latest updates from the original repository.
+```bash
+git pull upstream develop
+```
+4. Push the changes to your fork.
+```bash
+git push origin develop
+```
+
+## Content
+
+Every PR should correspond to a specific issue in the issue tracker. Tag the issue that the PR resolves (e.g., "This PR closes #1"). Keep PR content concise and focused on resolving a single issue. Additional changes should be made in separate PRs.
+
+## CI Tests
+
+All PRs must pass CI tests before being merged. Resolve any issues causing test failures and justify any modifications to unit tests in the PR description.
+
+## Style Guide
+
+Adhere to the following style guidelines when contributing to WaveDiff:
+
+1. Compatibility: Ensure compatibility with specified Python package versions.
+2. PEP8 Standards: Follow PEP8 standards for code formatting.
+3. Docstrings: Provide docstrings for all modules, methods, and classes following numpydoc standards.
+4. Existing Code: Use existing code as a reference for style conventions.
+5. String Formatting: Prefer single quotes over double quotes for strings, and use explicit floats.
+6. Line Length: Split long lines (>79 characters) using parentheses for readability.
+7. String Concatenation: Use f-strings for string formatting and explicit concatenation with a `+` at the beginning of each line.
+
+These guidelines will help maintain code consistency and readability throughout the project.
+
+Feel free to customize these guidelines further to better suit the specific needs and conventions of the WaveDiff project.

DEV_WORKFLOW.md

@@ -0,0 +1,118 @@
+# **WaveDiff Development Plan**
+
+## 1.  **Define a Milestone**
+
+
+  * **Purpose**: Milestones mark the completion of project cycles and achievement of predefined goals. A milestone is a timeline point marking the end of a project cycle, where a set of goals defined at the start of the cycle have been completed.  Goals could be tasks associated with feature development, testing phase completion, etc. List & Open issues. 
+
+  * **Types of Milestones:** Differentiate between major, minor and patch release releases to track progress effectively.
+
+
+Make a milestone related to a release on possibly a minor release schedule (e.g. monthly schedule). Differentiate between the different types of releases (minor, major, patch).
+
+## 2.  **Git Workflow Branching Model (Made with** [**mermaid**](https://mermaid.js.org)**)**
+![](assets/branching_model.png)
+
+   *   **main**: Stores official release history with tagged version numbers (see top row in the diagram above).
+
+   *   **develop**: This branch is the integration branch for features.
+
+   *   **feature**: Branch off of develop for new feature development.  Features get merged to develop (never to main).
+
+   *   **bug**: For fixing specific bugs introduced during the production phase.
+
+   *   **hotfix**: Quickly corrects bugs in the latest release version; branched off main.
+
+
+## 3.  **New Branch naming conventions**
+
+
+Branches created for the purpose of a Pull Request should be directly related to an open issue within the project’s issue tracker.  This ensures that all code changes are tied to specific tasks or features, facilitating better organisation and tracking of contributions.Below are the branch naming conventions:
+
+   *   **Feature**: feature/issue-/short-description
+
+   *   **Bug**: bug/issue-/short-description
+
+   *   **Hotfix**: hotfix/issue-/short-description
+
+
+Replace with the corresponding issue number and provide a brief description of the changes in \`short\_description\`.
+
+## 4.  **Feature branch creation** 
+
+
+*   Pull the latest changes from the remote repository
+
+*   Checkout develop
+
+*   Create a new feature branch
+
+*   Ensure the feature branch’s commits align with the defined scope
+
+
+**Tip**: Keep feature branch development focused on the defined scope outlined in the corresponding issue. Avoid introducing unrelated changes. Instead, open a new issue for out-of-scope features or bugs, creating a separate branch for their development.
+
+## 5.  **Completion of development** 
+
+
+*   Run training and metrics validation tests locally to confirm no breaking behaviour or errors were introduced.  Include test reports as per the PR template.
+
+*   Open a Pull Request to start the review process, ensuring to map the branch correctly to the target branch (i.e. feature\_branch -> develop or hotfix\_branch -> main).
+
+*   In the description of the Pull Request, explicitly state whether the PR resolves or closes an open issue by using one of the following formats:
+
+    *   "Solves #"
+
+    *   "Closes #"
+
+
+Example: "Solves #12345" or "Closes #8679".
+
+*   Ensure that the PR meets the defined requirements and passes Continuous Integration (CI) tests.
+
+*   Assign a reviewer, assign yourself as assignee, select the correct project, choose the correct label that describes the nature of the issue (e.g. bug, enhancement, etc), choose Milestone if applicable if the issue is associated with a specific milestone or target release.
+
+*   Address reviewer feedback in threads and iterate as needed, implementing the requested changes or explaining why the task is implemented in the manner it is.  Respect the rule: Whoever opens the thread/conversation in the Pull Request is responsible for closing it.
+
+
+## 6.  **Merging Pull Requests** 
+
+
+*   Approval and Merging: Once the reviewer approves the PR and all feedback is addressed, merge the feature branch into develop.  Note, it is the reviewer who is responsible for merging the PR when satisfied with the changes.
+
+
+## 7.  **Preparing for a Release**
+
+
+*   Each milestone targets a release (feature, patch, etc).
+
+*   Open a PR from develop to main upon completing a milestone
+
+*   Ensure all checklist items for the release are completed.
+
+*   Merge the PR into main and tag the release.
+
+
+## 8.  **Continuous Improvement**
+
+
+*   Regularly review and refine the workflow based on team feedback and lessons learned.
+
+*   Encourage collaboration and communication among team members to streamline processes and enhance productivity.
+
+
+## 9.  **Documentation and Training**
+
+
+*   Maintain up-to-date documentation outlining the development workflow and procedures.
+
+*   Provide training to new team members and ensure existing members are familiar with the workflow and best practices.
+
+
+## 10.  **Automation and Tooling**
+
+
+*   Explore automation tools to streamline repetitive tasks, such as testing, code formatting, and deployment.
+
+*   Integrate with CI/CD pipelines for automated testing and deployment processes.
+

docs/source/index.rst

@@ -26,4 +26,10 @@ cite :cite:t:`Liaudat:23`.
 .. |link-to-issues| raw:: html
 
   <a href="https://github.com/CosmoStat/wf-psf/issues/new"
-  target="_blank">open an issue</a>
+  target="_blank">open an issue</a>
+
+Contributing
+------------
+
+For information on how to contribute to the development of WaveDiff, see
+`Contributing to WaveDiff <../../CONTRIBUTING.md>`_.