How to Contribute

Open an Issue¶

If you encounter a bug, have a question, or want to suggest a new feature, you can open an issue using the provided templates. Follow these steps:

1. Go to the Issues Tab:

   • Navigate to one of the GitHub repositories below and click on the Issues tab.

     • molass-library for the library codes or their function reference,

     • molass-develop for the contents of this book,

     • molass-tutorial for the contents of its book,

     • molass-essence for the contents of its book.

2. Check for Existing Issues:

   • Search the existing issues to see if someone else has already reported the same problem or made a similar suggestion.

3. Create a New Issue:

   • If no similar issue exists, click the New Issue button and select the appropriate template (e.g., Bug Report, Feature Request) or other options listed below.

4. Describe the Issue:

   • For issue templates, provide the required details in the template fields. The template will guide you on what information to include.

   • For a blank issue, describe it freely.

   • In the forum, ask support or anything to the community.

5. Submit the Issue:

   • Once you’ve described the issue, click Submit New Issue.

Create a Pull Request¶

See the exercise below generated by GitHub Copilot.

Exercise: Submitting a Pull Request¶

As a contributor, your role is to propose changes to the project by creating a pull request. Follow these steps to practice:

1. Fork the Repository:

   • Go to the GitHub repository and click the Fork button to create your own copy of the repository.

2. Clone Your Fork:

   • Clone your forked repository to your local machine:

git clone https://github.com/<your-username>/<repository-name>.git
cd <repository-name>

3. Create a New Branch:

   • Create a branch for your changes:

4. Make Changes:

   • Edit files or add new ones. For example, update the README.md file:

5. Commit Your Changes:

   • Stage and commit your changes:

git add README.md
git commit -m "Update README with an example section"

6. Push Your Changes:

   • Push your branch to your forked repository:

git push origin feature/update-readme

Exercise: Reviewing and Merging a Pull Request¶

This section is addressed to collaborators who have stonger privileges over contirbutors (in the narrow sense).

As a collaborator, your role includes reviewing and merging pull requests from contributors. Follow these steps to practice:

1. Review the Pull Request:

   • Open a pull request submitted by a contributor.

   • Check the code for:

     • Functionality: Does the code work as intended?

     • Style: Does it follow the project’s coding standards?

     • Clarity: Is the code easy to understand and well-documented?

     • "Impact: Does it introduce any bugs or conflicts?

2. Request Changes (if needed):

   • If you find issues, leave constructive comments on specific lines of code.

   • Suggest improvements or ask for clarification where necessary.

3. Test the Code:

   • Pull the contributor’s branch to your local machine:

git fetch origin <branch-name>
git checkout <branch-name>

• Run the tests or manually verify the functionality.

4. Merge the Pull Request:

   • If the code meets all requirements, approve the pull request.

   • Merge it into the main branch using the GitHub interface or the command line:

git checkout main
git merge <branch-name>
git push origin main

5. Provide Feedback:

   • Leave a comment thanking the contributor and summarizing the changes.