ASKCOS

Appearance

ASKCOS Contributor Guidelines ​

This page goes over some general information about contributing to ASKCOS. More detailed instructions for setting up a development environment can be found in the Frontend and Python development guides.

Code of Conduct ​

Help us keep ASKCOS open and inclusive. Please read and follow our [Code of Conduct](ASKCOS Contributor Code of Conduct).

What do I need to know to help? ​

We would encourage you to contribute to ASKCOS and help make it better than it is today! If you are looking to help with a code contribution, ASKCOS uses:

  1. python
  2. pyTorch
  3. tensorflow
  4. Vue
  5. FastAPI
  6. Cypress
  7. Flow

If you don't feel ready to make a code contribution yet, no problem! You can also check out the documentation issues [link to the docs label or tag in GitLab] or the design issues that we have [link to design label or tag in GitLab].

If you are interested in making a code contribution and would like to learn more about the technologies use in ASKCOS, check out the list below:

  • Documentation (link)
  • Tutorials (link)
  • Blog posts (link)
  • FAQ's (link)

Reporting and/or fixing a bug ​

If you find a bug in the source code, you can help us by submitting an issue to our GitLab Repository. Even better, you can submit a Merge Request with a fix.

Feature Request ​

You can request a new feature by submitting an issue to our GitLab Repository.

If you would like to implement a new feature, please consider the size of the change in order to determine the right steps to proceed:

  • For a Major Feature, first open an issue and outline your proposal so that it can be discussed. This process allows us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project. Note: Adding a new topic to the documentation, or significantly re-writing a topic, counts as a major feature.
  • Small Features can be crafted and directly submitted as a Merge Request.

Submitting an Issue ​

Before you submit your bug report or feature request please:

  • Search GitLab MR's and GitLab Issues for an open or closed MR or issue that relates to your submission. You don't want to duplicate existing efforts and may find a workaround/fix already exists.
  • Be sure that an issue describes the problem you're fixing, or documents the design for the feature you would like to add.
  • Provide a minimal test case so the bug can be isolated and reproduced. This allows confirmation of the bug and ensures we are addressing the correct problem. Bug reports will be closed if test cases can not be provided and the bug can not be easily replicated.
  • Bug/Issues can be reported through GitLab's issue tracker and then selecting the project/repo (big blue button on the top right of the screen) that has the issue.

Process to contribute to ASKCOS ​

Cloning the repository ​

Never made an open source contribution before? Wondering how contributions work in the in our project? Here's a quick rundown!

  1. Find an issue that you are interested in addressing or a feature that you would like to add.
  2. Please sign our Contributor License Agreement (CLA) before sending PRs. We cannot accept code without a signed CLA. Make sure you author all contributed Git commits with email address associated with your CLA signature.
  3. Fork the relevant ASKCOS repo.
  4. Clone the repository to your local machine using
    shell
    git clone https://gitlab.com/mlpds_mit/askcosv2/repo_name.git .

Create a new branch and add your fix ​

  1. Create a new branch for your fix using

    shell
    git checkout -b branch-name-here

  2. Make the appropriate changes for the bug you are trying to fix or the feature that you want to add. including all appropriate test cases

  3. Follow our Coding Guidelines.

  4. Run the full ASKCOS test suite, as described in the [developer documentation][dev-doc], and ensure that all tests pass.

Submit a Pull request ​

  1. Use the command to store the changes

    shell
    git commit --all
    • Note: the optional commit --all command line option will automatically "add" and "rm" edited files.
    • Commit your changes using a descriptive commit message that follows our [commit message conventions](Commit Message Format). This is important because the release notes are automatically generated from these messages.

  2. Push the changes to the remote repository using

    shell
    git push origin branch-name-here

  3. Submit a pull request to the repository.

  4. Wait for the pull request to be reviewed by a maintainer.

  5. Make changes to the pull request if the reviewing maintainer recommends them.

Reviewing a Merge Request ​

The ASKCOS team reserves the right not to accept merge requests from community members who haven't been good citizens of the community. Such behavior includes not following the [ASKCOS Code of Conduct](ASKCOS Contributor Code of Conduct) and applies within or outside of ASKCOS managed channels.

Addressing review feedback ​

If we ask for changes via code reviews then:

  • Make the required updates to the code.

  • Re-run the ASKCOS test suites to ensure tests are still passing.

  • Create a fixup commit and push to your GitLab repository (this will update your Merge Request):

    shell
    git commit --all --fixup HEAD
git push

Updating the commit message ​

A reviewer might often suggest changes to a commit message (for example, to add more context for a change or adhere to our [commit message format](Commit Message Format). In order to update the commit message of the last commit on your branch:

  1. Check out your branch:

    shell
    git checkout branch-name-here

  2. Amend the last commit and modify the commit message:

    shell
    git commit --amend

  3. Push to your GitLab repository:

    shell
    git push --force-with-lease

NOTE:
If you need to update the commit message of an earlier commit, you can use git rebase in interactive mode. See the git docs for more details.

After your Merge request is merged ​

After your merge request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

  • Delete the remote branch on GitLab either through the GitLab web UI or your local shell as follows:

    shell
    git push origin --delete branch-name-here

  • Check out the main branch:

    shell
    git checkout main -f

  • Delete the local branch:

    shell
    git branch -D branch-name-here

  • Update your local main with the latest upstream version:

    shell
    git pull --ff upstream main

Coding Rules ​

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested by one or more specs (unit-tests).
  • All public API methods must be documented.
  • Please follow our coding [style guide](Style Guide).
  • Format the [commit message](Commit Message Format) accordingly.

Revert commits ​

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit.

The content of the commit message body should contain:

  • information about the SHA of the commit being reverted in the following format: This reverts commit <SHA>,
  • a clear description of the reason for reverting the commit message.

Where can I go for help? ​

If you need help, you can ask questions on our mailing list, IRC chat, or [list any other communication platforms that your project uses].

Signing the CLA ​

(this is a google CLA, we should have similar in MIT)

Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code changes to be accepted, the CLA must be signed.

If you have more than one GitLab accounts, or multiple email addresses associated with a single GitLab account, you must sign the CLA using the primary email address of the GitLab account used to author Git commits and send pull requests.

Released under the MIT License.

Copyright © 2024 MIT MLPDS