7. How to Contribute

7.1. 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.

Menu Item	Menu Action
Bug Report	Open an issue with template
Feature Request	Open an issue with template
Blank issue	Open a blank issue

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.

7.2. Create a Pull Request

See the exercise below generated by GitHub Copilot.

7.3. 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

7.4. 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.