Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
160 lines (119 loc) · 11 KB

CONTRIBUTING.md

File metadata and controls

160 lines (119 loc) · 11 KB
Raw

How to Contribute to ThermoEngine

We welcome contributions to this project and ask that you follow these procedures and code of conduct when making your contribution.

This information is out of date and will be updated soon; however, much of the information is still useful. A key point of departure is that merge requests should go to the "develop" branch (which may soon be renamed to something like "staging". The main branch always stays fixed at the most recent developer release.

1️⃣ Fork the repository.

The repository is publicly assessible, but we discourage branching or modfying the master branch, so the first step in contributing is to fork the repository to your private workspace on GitLab.

  1. Click the Fork button on the top right.
  2. Choose a namespace (your home on GitLab) from the list provided. This action creates a copy of the repository in that location.
  3. (Recommended) Rename your forked repository to, for example, ThermoEngineMyInitials, to avoid confusing it with the source repository.
    1. On GitLab, go to Settings > General, enter a new project name, and click Save Changes.
    2. (IMPORTANT) Make sure to keep the path name the same as your project name. Go to Settings > General, and expand the Advanced section. Under Change path, enter the path name, and click Change path.

2️⃣ Set up your forked repository to mirror the source repository.

Note: The automatic mirroring setup described in this section works only if you have a paid GitLab membership. You can still work quite effectively without this step, so do not worry if you do not have a GitLab membership.

After forking, set up your forked repository to mirror the source repository. This ensures that all future updates to the source repository are included in your fork. Avoid working directly in the master or Documentation branch of your forked repository to ensure that the mirroring process does not break or encounter a conflict as you develop code.

To set up mirroring on GitLab:

  1. At your forked repository, go to Settings > Repository, and expand the Mirroring repositories section.
  2. Enter https://gitlab.com/ENKI-portal/ThermoEngine in the Git repository URL field.
  3. From the Mirror direction dropdown menu, choose Pull.
  4. Click Mirror repository.

3️⃣ Restrict access if desired.

If you would like to restrict access to your project, it is important that you do not reset access to Private. That action will break the fork relationship. Instead, do the following procedure.

To restrict access to your project:

  1. Go to Settings > General, and expand the Visibility, project, features, permissions section.
  2. (IMPORTANT!) Leave Project visibility set to Public.
  3. Set permissions for Issues, Repository, Forks, Pipelines, Wiki, Snippets and Pages to Only Project Members.
  4. Click Save changes.

Your project files will be visible only to you.

4️⃣ Create a development branch from master in your forked repository.

Now that your mirror is set up, create a development branch from master in your forked repository, and give it a name, which we will assume is develop. Consider adopting a development workflow such as that recommended by GitFlow.

5️⃣ Checkout the develop branch.

Check out the develop branch, and create your new code feature in that branch. Most users will want to work locally, rather than at GitLab.

To work locally:

  1. Clone the forked repository on GitLab to your local system using Git commands in a terminal or some GUI Git user interface (e.g., Tower, GitKrachen).
  2. Navigate to the local cloned source directory.
  3. Check out the develop branch of the clone.
  4. Revise code in the locally cloned workspace.

To setup a convenient local development environment, it is recommended that you setup automatic login for your local machine (using either a personal access token over https or ssh-keys over ssh). Both methods work, but we recommend the standard approach using personal access tokens.

To setup a automatic login using a personal access token:

  1. Login to GitLab.
  2. Click on your profile picture in the upper right and select Edit profile.
  3. Click on the Access Tokens button in the vertical left-hand menu bar.
  4. Select a Token name (e.g. 'work-laptop') and select the desired scope (api gives complete control for all possible use-cases).
  5. Click Create personal access token
  6. Copy the token value to a secure location (e.g. password manager). This token must be kept private as it grants full access to your repo without any passwords needed. Do not lose the token as it is unrecoverable from GitLab. If you do lose it, you must use these steps to generate another.
  7. Store your token in your local git repo using the following command at the command line: git remote set-url origin https://oauth2:TOKEN@gitlab.com/USERNAME/YOUR_REPO.git
    • be sure to replace TOKEN, USERNAME, and YOUR_REPO with your personal info.

6️⃣ After finishing your work, add it back to the repository.

When you are ready, add your code additions or revisions back to the ThermoEngine repository.

To add your code additions or revisions back to the ThermoEngine repository:

  1. Do one of the following:
    • If working locally:
      1. Use the Git pull command to update the cloned master branch from the forked repository master branch.
      2. Use Git to merge your cloned master branch into your cloned develop branch. These steps ensure that the latest changes to master in the source repository are reflected in your code revisions.
      3. Use Git to commit the develop branch.
      4. Use the Git push command to send code revisions on that branch back up to the forked repository.
    • If working on GitLab:
      • Merge your forked repository master branch into your develop branch. This step ensures that the latest changes to master in the source repository are reflected in your code revisions.
  2. In GitLab, navigate to the top view of your forked repository.
  3. In the left-hand pane, click Merge requests and then click New merge request.
  4. For Source branch, choose your forked project’s develop branch. For Target branch, choose the original Enki-portal/ThermoEngine master branch.
  5. Click Compare branches and continue. You can now optionally add labels, add a milestone, and assign the merge request to someone who can review your changes.
  6. Click Submit merge request.

7️⃣ Resolve any conflicts as instructed by maintainer.

At this stage, your merge request will be reviewed by a maintainer of the ThermoEngine repository, and one of the following will occur:

  • The changes will be accepted.
  • The maintainer will either resolve any conflicts or redirect the request back to you with instructions for resolution.

8️⃣ Congratulate yourself!

That's it! Congratulate yourself. You have just made a contribution to the ThermoEngine code base and the ENKI project.

Versioning Standards for ThermoEngine

  • Currently working towards the release of v2.0.0
  • Major API changes should be restricted to major version increments (e.g. moving to v3.0.0)
  • New features should correspond to minor version increments, i.e. v2.1.0
  • Bug fixes/patches iterate the final patch version number: e.g. v2.0.1
  • When ready to lock in the new features for a minor release, a new branch should be created with a name like v2.0.x
    • The current dev version (from main) can then be moved to being a release candidate on the new branch, i.e. tag v2.0.0.rc1
    • Development of new features continues on main (with merge requests from develop), and "released" as dev versions, e.g. v2.0.0.dev1. The main branch always stays fixed to the most recent dev version.
  • Once v2.0.0 has been released, only non dev, non rc versions will be published on PyPI.

See example from astropy project here [[https://docs.astropy.org/en/latest/development/maintainers/maintainer_workflow.html]].

Release Procedure for ThermoEngine

  1. Check that the complete wheel building pipeline passes (or only very minor changes have been made since last passed).
  2. Merge any additional commits from main into develop (try a git merge main from develop)
  3. Rebuild the docs (this should be moved to being a pipeline at some point)
    • Bump the version number in doc/source/conf.py
    • in the doc/ directory: make clean
    • delete the doc/source/auto_examples/ directory (unless there is no need to rebuild these)
      • if something fails, you may need to delete manual_examples and add it back later?
    • in the doc/ directory: make html
    • check that the gallery has been built correctly by navigating to the files in a browser locally (go to doc/build/html/index.html)
      • open several notebooks
      • check binder link
  4. Update the changelog (could be done later in the process too, but now is a good time!)
    • Commit all changes to develop
  5. Do a final pull on develop, push any final updates
  6. Create a merge request for develop into main on Gitlab
    • set to auto merge
  7. Once tests have passed, complete the merge
    • git pull main to local machine
  8. Increment the version number on the main branch (and update changelog on main if not already done on develop)
    • e.g. 2.0.0.dev2
    • This must be done for both thermoengine/pyproject.toml and thermoengine_utils/pyproject.toml
    • push changes to main
  9. Create a tagged release corresponding to the version number
    • ensure that all architectures complete in pipeline
    • NOTE: Gitlab shared runners sometimes hang and you must stop and restart the hung job to complete the pipeline
  10. Verify that the tagged release pipeline succeeds and the package can be installed via pip for the "latest stable developer version" using instructions in README.md
  11. Increment the version number in binder/requirements.txt.
  • I think that only a single version of the binder is generally available (or at least a single version for any given branch), therefore we don't want to update this until the new wheels are available. Otherwise it will temporarily break the binder.
  1. Merge updates from main (i.e., version number incremenet) back into develop.
  2. Update the docs on readthedocs (specifically the stable-dev version)
  • login to readthedocs.org and find ThermoEngine project
  • Click on latest, and then Settings gear icon in upper right
  • Update Default branch to point to newest tagged release and Save
  • Validate that change has propagated to thermoengine.readthedocs.org
  1. Notify userbase on ENKI Zulip in #releases/releases testing

Final Release to PyPI

  • Once ready, update to PyPI along with update to enki-portal.org
  • NOTE: This workflow has not yet been created

Code of Conduct for Contributors

Please note that we have a code of conduct. Please follow it in all your interactions with the project.